@oxy.so/contracts 1.0.0

package/dist/esm/deviceSession.js

@@ -0,0 +1,161 @@
+import { z } from 'zod';
+export const sessionAccountSchema = z.object({
+    accountId: z.string(),
+    sessionId: z.string(),
+    authuser: z.number().int().nonnegative(),
+    operatedByUserId: z.string().optional(),
+});
+export const deviceSessionStateSchema = z.object({
+    deviceId: z.string(),
+    accounts: z.array(sessionAccountSchema),
+    activeAccountId: z.string().nullable(),
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.number(),
+});
+export const activeTokenSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+});
+export const deviceSessionSyncSchema = z.object({
+    state: deviceSessionStateSchema,
+    activeToken: activeTokenSchema.nullable(),
+});
+/* -------------------------------------------------------------------------- */
+/*  Device-secret token mint (phase 2c — zero-cookie transport)               */
+/* -------------------------------------------------------------------------- */
+/**
+ * Request body for `POST /session/device/token` — the client presents the
+ * `deviceId` it stored first-party plus the opaque `deviceSecret`. NO bearer:
+ * possession of the secret IS the proof of device ownership. The server matches
+ * `sha256(deviceSecret)` against the device's stored `secretHash` (constant-time)
+ * and mints a short access token for the device's active account.
+ *
+ * `accountId` pins the mint to ONE account of that device instead of whichever
+ * account is currently active. It exists for identity-bound clients (Commons),
+ * whose authenticated user is determined by a local cryptographic key and must
+ * never follow an account switch made by another app on the same device. The
+ * account must already be a member of the device session; the mint NEVER
+ * mutates `activeAccountId`, so pinning is read-only with respect to the device
+ * state every other app observes.
+ */
+export const deviceTokenMintRequestSchema = z.object({
+    deviceId: z.string().min(1),
+    deviceSecret: z.string().min(1),
+    accountId: z.string().min(1).optional(),
+});
+/**
+ * Wire shape of a successful `POST /session/device/token`: the freshly-minted
+ * short access token for the active account, its expiry, the device secret the
+ * client must persist (`nextDeviceSecret` — on mint this echoes the presented
+ * secret unchanged so concurrent refreshes from multiple origins do not race),
+ * and the projected device-session state. Sign-in rotates the secret via
+ * `issueDeviceSecret`; mint does not.
+ */
+export const deviceTokenMintResponseSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    nextDeviceSecret: z.string(),
+    state: deviceSessionStateSchema,
+});
+/* -------------------------------------------------------------------------- */
+/*  Instant cross-app session sync (token-free socket signal)                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Name of the token-free Socket.IO event emitted to room `user:<userId>` on
+ * every DeviceSession mutation that changes what is signed in for that user.
+ *
+ * This is a pure SIGNAL — it carries NO access token, NO deviceSecret and NO
+ * account bodies. A client that receives it re-fetches its authenticated
+ * session/account state (`GET /session/device/state`, `GET /accounts`). Unlike
+ * `session_state` (scoped to `device:<deviceId>`, i.e. a single origin), this
+ * reaches ALL of a user's connected sockets across their devices/origins so
+ * every Oxy app reflects an add / switch / signout instantly.
+ */
+export const SESSION_ACCOUNTS_CHANGED_EVENT = 'session_accounts_changed';
+/**
+ * Why the signed-in set changed:
+ *  - `login`   — a brand-new session was minted for the user (QR / cross-app authorize)
+ *  - `add`     — an account was registered onto a device set
+ *  - `switch`  — the active account on a device changed
+ *  - `signout` — one or all accounts were signed out of a device
+ *  - `revoke`  — a dead/revoked account was healed out of a device set
+ */
+export const sessionAccountsChangedReasonSchema = z.enum([
+    'login',
+    'add',
+    'switch',
+    'signout',
+    'revoke',
+]);
+/**
+ * Payload of {@link SESSION_ACCOUNTS_CHANGED_EVENT}. `revision` is the mutated
+ * DeviceSession revision for device-scoped reasons (`add`/`switch`/`signout`/
+ * `revoke`); for `login` (no device mutation at emit time) it is `0`. The
+ * payload is deliberately minimal and secret-free — the client refetches.
+ */
+export const sessionAccountsChangedEventSchema = z.object({
+    userId: z.string(),
+    revision: z.number().int().nonnegative(),
+    reason: sessionAccountsChangedReasonSchema,
+});
+/* -------------------------------------------------------------------------- */
+/*  Background credential — native background code with no JS runtime         */
+/* -------------------------------------------------------------------------- */
+/**
+ * Response from `POST /session/device/background-credential` — provisioned by
+ * the SDK WHILE THE APP IS RUNNING (bearer required, `deviceId` and account
+ * derived server-side from it) and consumed afterwards only by native
+ * background code, which has no JS runtime to mint a token for itself.
+ *
+ * Deliberately a SEPARATE credential from the rotating `deviceSecret`: that one
+ * rotates on every mint, so background code presenting it would become a second
+ * writer of a value the JS runtime depends on, and background code killed
+ * mid-rotation would silently sign the user out on the next cold start. Against
+ * this credential background code is the sole writer, and it can never rotate
+ * anything JS reads.
+ *
+ * The raw `secret` is returned exactly once, at provision time — never stored
+ * retrievably, never logged, never re-read. A caller that loses it provisions
+ * a new one.
+ *
+ * `expiresAt` is an unvalidated string, like every other expiry in this file:
+ * no consumer on the JS path interprets it (native background code parses it
+ * itself), and a `.datetime()` here alone would leave one strict field beside
+ * two lax ones. If expiry is ever validated it goes on all three at once, with
+ * the API's serializers checked against it — the producer is the same server.
+ */
+export const deviceBackgroundCredentialResponseSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+    accountId: z.string().min(1),
+    expiresAt: z.string(),
+});
+/**
+ * Request body for `POST /session/device/background-token` — presented by
+ * native background code with NO bearer and NO cookies: possession of the
+ * background `secret` IS the proof, as it is for the device-secret mint.
+ *
+ * Unlike that mint this one NEVER rotates the presented secret (hence no
+ * `next…` field to persist in the response), so background code interrupted
+ * anywhere between request and response leaves the credential intact and
+ * usable on its next run.
+ */
+export const deviceBackgroundTokenRequestSchema = z.object({
+    deviceId: z.string().min(1),
+    secret: z.string().min(1),
+});
+/**
+ * Wire shape of a successful `POST /session/device/background-token`: the short
+ * access token, its expiry, and the account the token belongs to — the last so
+ * a caller can key cached data per account and drop data belonging to a
+ * foreign one.
+ *
+ * Carries NO device state — no account list, no `activeAccountId`, no
+ * `revision`, unlike {@link deviceTokenMintResponseSchema} — deliberately, to
+ * cap what a compromised credential record yields.
+ */
+export const deviceBackgroundTokenResponseSchema = z.object({
+    accessToken: z.string(),
+    expiresAt: z.string(),
+    accountId: z.string().min(1),
+});

package/dist/esm/emailAgentContext.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+export const emailContextAddressSchema = z.object({
+    name: z.string().optional(),
+    address: z.string().email(),
+}).strict();
+export const emailContextMailboxSchema = z.object({
+    mailboxId: z.string().min(1),
+    name: z.string(),
+    path: z.string(),
+    totalMessages: z.number().int().nonnegative(),
+    unseenMessages: z.number().int().nonnegative(),
+}).strict();
+export const emailContextMessageSchema = z.object({
+    messageId: z.string().min(1),
+    mailboxId: z.string().min(1),
+    from: emailContextAddressSchema,
+    subject: z.string(),
+    receivedAt: z.string().datetime(),
+    seen: z.boolean(),
+    answered: z.boolean(),
+}).strict();
+export const emailAgentContextSchema = z.object({
+    accountId: z.string().min(1),
+    resourceMailboxId: z.string().min(1).nullable(),
+    generatedAt: z.string().datetime(),
+    mailboxes: z.array(emailContextMailboxSchema),
+    recentUnread: z.array(emailContextMessageSchema),
+    needsResponse: z.array(emailContextMessageSchema),
+}).strict();

package/dist/esm/followGraph.js

@@ -0,0 +1,27 @@
+/**
+ * The follow graph wire contract (`/v2/follows`).
+ *
+ * These types are the boundary between the API that owns the graph and every
+ * application that reads it. They live here — not in the API and not in the
+ * SDK — because both ends have to agree, and a shape defined on one side is a
+ * shape the other side re-declares slightly differently within a release or two.
+ *
+ * ## Why the state is three fields and not a boolean
+ *
+ * A user can follow something globally and turn it off in ONE application. That
+ * is a state the user themselves created, so the client has to be able to see
+ * it and say so — "following, but not shown here" is a sentence a boolean
+ * cannot express. `globalState`, `applicationMode` and `effectiveState` are
+ * therefore reported separately, and only the last one answers "does this
+ * appear in my feed right now".
+ *
+ * ## Why kinds are strings
+ *
+ * `FollowTargetKind` is a plain `string`, not a union. Applications register
+ * their own kinds at runtime (`mercaria.store`, `syra.artist`), so a union here
+ * would mean every new application in the ecosystem needs a release of this
+ * package before it can follow anything. The namespace rule is enforced by the
+ * database, which is the one place that can enforce it for applications this
+ * package has never heard of.
+ */
+export {};

package/dist/esm/identity.js

@@ -0,0 +1,255 @@
+/**
+ * Self-sovereign identity API contracts.
+ *
+ * SINGLE SOURCE OF TRUTH for the wire shape of Oxy's AtProto/Bluesky-flavoured
+ * identity & portability layer: the W3C DID document the API derives on demand,
+ * the signed-record envelope clients sign with their cryptographic key (and the
+ * server verifies), the verified-domain badge, the auth-method ↔ DID
+ * verification-method mapping, and the signed data-export ("credible exit")
+ * bundle. The API validates its OUTPUT against these schemas; every consumer
+ * (the Commons vault app, `@oxy.so/core`'s identity mixin) validates its INPUT
+ * against the same definitions, so producer and consumers cannot drift.
+ *
+ * Design anchors (from the identity-layer plan):
+ *  - DID = `did:web:oxy.so:u:<userId>` — anchored on the stable account id, NOT
+ *    the keypair. The keypair is a *verification method* that maps 1:1 to the
+ *    existing `authMethods[]`. Custodial (password-only) users get a DID
+ *    controlled solely by Oxy (`OXY_DID`); creating a Commons key upgrades them
+ *    to self-sovereign (`controller = [userDid, OXY_DID]`); fully reversible.
+ *  - Verification methods use the secp256k1 `EcdsaSecp256k1VerificationKey2019`
+ *    type with `publicKeyHex` for now (a `Multikey`/`publicKeyMultibase` form may
+ *    be added later — see the plan's open risks).
+ *  - Signed records carry an envelope whose signing input is the canonical-JSON
+ *    of every field EXCEPT `publicKey` and `signature`; `alg` is
+ *    `ES256K-DER-SHA256` (secp256k1 over the SHA-256 of the canonical bytes,
+ *    DER-encoded signature) — the same scheme `SignatureService` uses.
+ *
+ * Explicit-`interface` exports (DidDocument, SignedRecordEnvelope, ExportBundle,
+ * VerifiedDomain, AuthMethodsResponse and their sub-parts) follow the same
+ * rationale as `UserNameResponse` in `./userResponse`: a `z.infer<>` of a nested
+ * object schema can degrade under a consumer's `moduleResolution: "node"`
+ * (node10) resolution, so the load-bearing response shapes are declared as
+ * literal interfaces and the runtime schemas are annotated `z.ZodType<Interface>`
+ * — the emitted `.d.ts` then states the field types verbatim and survives BOTH
+ * `node` and `bundler` resolution. Request schemas (no nested-object hazard) are
+ * inferred via `z.infer<>`.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo. ESM-safe (no
+ * `require()`).
+ */
+import { z } from 'zod';
+// The option schemas are left UN-annotated so they keep their concrete
+// `ZodObject` type — `z.discriminatedUnion` requires object options and an
+// explicit `z.ZodType<>` annotation would erase the shape it discriminates on.
+// `z.object` already infers each option's type exactly (id/type/controller +
+// the key field), so the union is structurally `VerificationMethod`.
+const secp256k1VerificationMethodSchema = z.object({
+    id: z.string(),
+    type: z.literal('EcdsaSecp256k1VerificationKey2019'),
+    controller: z.string(),
+    publicKeyHex: z.string(),
+});
+const multikeyVerificationMethodSchema = z.object({
+    id: z.string(),
+    type: z.literal('Multikey'),
+    controller: z.string(),
+    publicKeyMultibase: z.string(),
+});
+export const verificationMethodSchema = z.discriminatedUnion('type', [
+    secp256k1VerificationMethodSchema,
+    multikeyVerificationMethodSchema,
+]);
+export const didServiceSchema = z.object({
+    id: z.string(),
+    type: z.string(),
+    serviceEndpoint: z.string(),
+});
+export const didDocumentSchema = z.object({
+    '@context': z.array(z.string()),
+    id: z.string(),
+    controller: z.array(z.string()),
+    verificationMethod: z.array(verificationMethodSchema),
+    authentication: z.array(z.string()),
+    assertionMethod: z.array(z.string()),
+    alsoKnownAs: z.array(z.string()),
+    service: z.array(didServiceSchema),
+});
+export const signedRecordEnvelopeSchema = z
+    .object({
+    version: z.union([z.literal(1), z.literal(2)]),
+    // Open, app-defined category (see the `type` doc above). The Oxy STORE
+    // re-narrows to `oxySignedRecordTypeSchema`; an app to its own constant.
+    type: z.string().min(1),
+    subject: z.string(),
+    issuer: z.string(),
+    record: z.record(z.unknown()),
+    issuedAt: z.number(),
+    seq: z.number().int().nonnegative().optional(),
+    prev: z.string().nullable().optional(),
+    collection: z.string().min(1).optional(),
+    rkey: z.string().min(1).optional(),
+    publicKey: z.string(),
+    alg: z.literal('ES256K-DER-SHA256'),
+    signature: z.string(),
+})
+    .superRefine((env, ctx) => {
+    if (env.version === 2) {
+        // v2 REQUIRES the hash-chain fields. `prev` may be `null` at genesis,
+        // but the key must be present (it is part of the signed bytes), so we
+        // reject only when it is entirely absent.
+        if (typeof env.seq !== 'number') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev === undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `prev` (use `null` at genesis)',
+                path: ['prev'],
+            });
+        }
+        if (typeof env.collection !== 'string') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `collection`',
+                path: ['collection'],
+            });
+        }
+        if (typeof env.rkey !== 'string') {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v2 envelope requires `rkey`',
+                path: ['rkey'],
+            });
+        }
+    }
+    else {
+        // v1 FORBIDS the v2 chain fields entirely, so a legacy envelope keeps
+        // its exact byte shape and cannot smuggle unsigned chain metadata.
+        if (env.seq !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `seq`',
+                path: ['seq'],
+            });
+        }
+        if (env.prev !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `prev`',
+                path: ['prev'],
+            });
+        }
+        if (env.collection !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `collection`',
+                path: ['collection'],
+            });
+        }
+        if (env.rkey !== undefined) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: 'v1 envelope must not carry `rkey`',
+                path: ['rkey'],
+            });
+        }
+    }
+});
+export const verifiedDomainSchema = z.object({
+    domain: z.string(),
+    verifiedAt: z.union([z.string(), z.date()]),
+    method: z.enum(['dns-txt', 'well-known']),
+});
+/** Request body for `POST /identity/domains` — the domain to start verifying. */
+export const domainVerificationRequestSchema = z.object({
+    domain: z.string().trim().min(1),
+});
+/**
+ * The instructions the API returns when a domain verification is requested. The
+ * caller may prove ownership EITHER by publishing the `dns` TXT record OR by
+ * serving the `wellKnown` file; either path then satisfies
+ * `POST /identity/domains/:domain/verify`.
+ */
+export const domainVerificationInstructionsSchema = z.object({
+    domain: z.string(),
+    token: z.string(),
+    dns: z.object({
+        name: z.string(),
+        value: z.string(),
+    }),
+    wellKnown: z.object({
+        url: z.string(),
+        body: z.string(),
+    }),
+});
+export const authMethodEntrySchema = z.object({
+    type: z.enum(['identity', 'webauthn']),
+    linkedAt: z.union([z.string(), z.date()]),
+    verificationMethodId: z.string().optional(),
+    credentialId: z.string().optional(),
+    name: z.string().optional(),
+});
+export const authMethodsResponseSchema = z.object({
+    did: z.string(),
+    methods: z.array(authMethodEntrySchema),
+});
+export const exportAttestationSchema = z.object({
+    issuer: z.string(),
+    publicKey: z.string(),
+    alg: z.literal('ES256K-DER-SHA256'),
+    signature: z.string(),
+    signedAt: z.number(),
+});
+export const exportUsageReceiptSchema = z.object({
+    receiptId: z.string(),
+    requestId: z.string(),
+    settledAt: z.string(),
+    billedAmount: z.string(),
+    currency: z.string(),
+    outcome: z.string(),
+    resolvedModelReference: z.string(),
+    servingProvider: z.string(),
+    platformFeeOnly: z.boolean(),
+});
+export const exportLedgerEntrySchema = z.object({
+    entryId: z.string(),
+    kind: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+});
+export const exportUsageReservationSchema = z.object({
+    reservationId: z.string(),
+    requestId: z.string(),
+    status: z.string(),
+    reservedAmount: z.string(),
+    currency: z.string(),
+    createdAt: z.string(),
+    expiresAt: z.string(),
+});
+export const exportFinancialSectionSchema = z.object({
+    receipts: z.array(exportUsageReceiptSchema),
+    ledgerEntries: z.array(exportLedgerEntrySchema),
+    reservations: z.array(exportUsageReservationSchema),
+});
+export const exportBundleSchema = z.object({
+    '$schema': z.string(),
+    exportedAt: z.string(),
+    did: z.string(),
+    didDocument: didDocumentSchema,
+    profile: z.record(z.unknown()),
+    verifiedDomains: z.array(verifiedDomainSchema),
+    authMethods: z.array(authMethodEntrySchema),
+    signedRecords: z.array(signedRecordEnvelopeSchema),
+    appData: z.array(z.record(z.unknown())),
+    social: z.object({
+        following: z.array(z.string()),
+        followers: z.array(z.string()),
+    }),
+    financial: exportFinancialSectionSchema,
+    attestation: exportAttestationSchema.nullable(),
+    proof: exportAttestationSchema.optional(),
+});

package/dist/esm/inboxPush.js

@@ -0,0 +1,21 @@
+/**
+ * Canonical contract for Inbox new-mail push notifications.
+ *
+ * The Android channel id and payload `type` are wire contracts: Android 8+
+ * drops a notification whose channel the app has not created, and the client
+ * only routes taps it recognises. Two hand-typed copies of either string fail as
+ * "the notification never arrived" or "tapping does nothing" — the hardest push
+ * symptoms to diagnose.
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/** Android notification channel id the new-mail push is sent on. */
+export const INBOX_EMAIL_PUSH_CHANNEL = 'email';
+/** Runtime type discriminator of the new-mail push payload. */
+export const INBOX_EMAIL_PUSH_TYPE = 'oxy_inbox_new_message';
+export const inboxEmailPushDataSchema = z.object({
+    type: z.literal(INBOX_EMAIL_PUSH_TYPE),
+    messageId: z.string().min(1),
+    mailboxId: z.string().min(1),
+});