Context and shared context

context is the one request context every interface reads, plus consent-gated first-party context shared between peer apps of one owner on one machine.

context:
  group: acme-learning
  identity: auth
  purposes:
    personalise:
      description: "Use the same language and theme in every Acme app"
      attributes: [locale, theme]
      retention: 30d
      share-with: [prj_01JD8X]
  fields:
    attributes:
      favourite-subject: { type: string, enum: [maths, science] }
    events: [lesson.completed]
  sinks: []

import { context } from "mainsdk";

// sent only to peers named under the purpose, and only with the person's consent on both sides
await context.shared.put({ purpose: "personalise", attributes: { locale: "hi-IN", theme: "dark" } });

context:
  driver: builtin

Quick start

context:
  group: acme-learning
  identity: auth
  purposes:
    personalise:
      description: "Use the same language and theme in every Acme app"
      attributes: [locale, theme]
      retention: 30d
      share-with: [prj_01JD8X]

import { app } from "mainsdk";

const ctx = app().sharedContext;
const user = { id: "u_123" };

// 1. Ask: show the description and the apps that receive it, then record the person's answer.
const ask = ctx.consent.ask("personalise");
await ctx.consent.set(user, "personalise", true);

// 2. Share: sent only to peers named under the purpose, and only when both apps hold a yes.
const { sent, held, refused } = await ctx.shared.put(
  { purpose: "personalise", attributes: { locale: "hi-IN", theme: "dark" } },
  { user },
);

// 3. Read what peers shared with this app.
const { attributes } = await ctx.shared.get("personalise", { user });

Configuration

context:
  group: acme-learning          # required: lower-case letters, digits and dashes
  identity: auth                # auth | first-party | both
  purposes: {}                  # one entry per declared purpose, see below
  fields: {}                    # up to 16 extra attributes and event types
  sinks: [db]                   # optional onward copies: db or events

Purposes

Every flow is for a declared purpose. A purpose has a description shown to the person, the attributes and events it may carry, a retention (default 30d, at most 90d) and share-with, the peer apps that receive it. Consent is per purpose; there is no "all purposes" switch. Built-in attribute keys are locale, timezone, theme, reduced-motion, text-size, high-contrast and units. Declare up to 16 extra attributes and event types under context.fields:

context:
  fields:
    attributes:
      favourite-subject: { type: string, enum: [maths, science] }
      streak: { type: number }
    events: [lesson.completed]

A string field needs an enum or a max-length of at most 64.

Identity

identity: auth derives the id from the signed-in subject, so peers that sign people in through one issuer get the same cx_ id without exchanging the subject. identity: first-party makes a random id when the person first grants a purpose, stored in the group's store. The id differs per tenant and per group, and is never derived from a device, hardware, advertising id, IP address, fingerprint or email. The group key is 32 random bytes in <run>/context/<group>.key (mode 0600) and never leaves the machine.

What you get

context has two halves. The request context (context.current(), context.run()) is one place every interface reads who is calling and on which trace; it belongs to spec cohesion and is built: one AsyncLocalStorage in core/context.ts holds tenant, user, agent, region, trace, deadline and signal; adapters set it once per request; jobs, workflow runs and outbox rows save context.capture() and run inside context.restore(), so a log record carries the request's trace_id and agent in the job and every workflow step. Shared context (context.shared.*, context.identity.reset()) lets several MainSDK apps from one publisher on one machine share a small typed picture of a person (language, theme, accessibility settings, a finished lesson) so each app serves them better, and only because that person said yes to a stated purpose. It is not an ad-tracking SDK: no advertising or device id is ever involved, nothing leaves the machine unless you declare where, and the person can see it, export it, reset the id that links it and erase it everywhere.

Single apps and single serverless apps get nothing from shared context. For shared sign-in across separate deployments, use auth.

Calls

What it always does

• Nothing flows without a recorded purpose and consent in both apps. Without a yes here nothing is sent; a peer without its own yes drops the message and answers held.
• Only fields the purpose lists are sent or stored. Strings are at most 64 characters; fields labelled personal, sensitive, child or phi, and values that look like a secret, email, phone number or card, are refused (MAIN-CONTEXT-0004).
• Received context is stored per tenant, expires at the purpose's retention and is read only for the same tenant and person (MAIN-CONTEXT-0005 for a cross-tenant message).
• Withdrawing consent stops the flow at once and sends an erase to every peer that received it. A peer that is down gets the erasure queued and is listed as pending (MAIN-CONTEXT-0007).
• Every flow is audited with the purpose, the peer, field names and counts, never a value and never a raw user id.
• It stays on the host. The only onward copies are the sinks you declare under context.sinks (db or events); anything else is refused at check.
• A children's app (users.audience: children) must mark each purpose children: guardian-consent (MAIN-CONTEXT-0006).

See what is shared

mainsdk context (and mainsdk info) show the group, purposes, share-with, sinks and, per purpose, how many people consented and how many flows went out and came in. They hold no context id, user id or value.

Errors and checks

Each code's cause and fix is in check codes.

Swapping drivers

builtin is the only driver, so there is nothing to swap yet. Your calls do not depend on how peers are reached.

Testing

createTestApp builds the app from main.yaml, so app.sharedContext runs the same consent and minimisation rules in memory. The unit tests for the schema, consent, tenant isolation and erasure live in packages/sdk/test/context-shared.test.ts and packages/testing/test/context-shared.test.ts.

Next

• Share context between your apps
• Sign-in and identity
• Check codes