@oxy.so/contracts 2.1.0 → 3.0.0

package/dist/cjs/accountEmail.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMAIL_VERIFICATION_ERROR_CODES = exports.emailVerificationConfirmResponseSchema = exports.emailVerificationConfirmRequestSchema = exports.emailVerificationStartResponseSchema = exports.emailVerificationStartRequestSchema = exports.emailTicketSchema = exports.emailAddressSchema = exports.EMAIL_TICKET_TTL_MS = exports.EMAIL_CODE_MAX_ATTEMPTS = exports.EMAIL_CODE_TTL_MS = exports.EMAIL_CODE_LENGTH = exports.EMAIL_VERIFICATION_PURPOSES = void 0;
+/**
+ * Email codes and tickets (ADR 0030).
+ *
+ * A web account is a username and an email; a password and an authenticator
+ * app are optional and added later. The email is proven by a 6-digit code sent
+ * to it, and the proof is a short-lived one-use ticket the next step spends:
+ *
+ * - `signup`: the ticket lets `POST /auth/signup` create the account with that
+ *   email. `start` answers the same whether or not the address already has an
+ *   account, so it never tells anyone which emails have an Oxy account.
+ *
+ * Signing in by email (`signin`) and re-verifying before a sensitive change
+ * (`reauth`) use the same code, through their own routes (`signIn.ts`).
+ */
+const zod_1 = require("zod");
+/**
+ * - `signup`: above.
+ * - `signin`: the code (and link) of an email sign-in (`POST /auth/signin/email/start`).
+ * - `reauth`: a signed-in person proving it is them before a sensitive step
+ *   (`POST /users/me/reauth/email`): a password, an authenticator, deleting the
+ *   account, linking Commons.
+ */
+exports.EMAIL_VERIFICATION_PURPOSES = ['signup', 'signin', 'reauth'];
+/** Digits in a code. */
+exports.EMAIL_CODE_LENGTH = 6;
+/** How long a code can be confirmed. */
+exports.EMAIL_CODE_TTL_MS = 10 * 60 * 1000;
+/** Wrong codes before a verification is spent and a new code is needed. */
+exports.EMAIL_CODE_MAX_ATTEMPTS = 5;
+/** How long a confirmed code's ticket can be spent. */
+exports.EMAIL_TICKET_TTL_MS = 15 * 60 * 1000;
+/** An email address as the API stores it: trimmed and lowercase. */
+exports.emailAddressSchema = zod_1.z.string().trim().toLowerCase().min(3).max(254).email();
+/** An opaque one-use ticket (32 random bytes, base64url). */
+exports.emailTicketSchema = zod_1.z
+    .string()
+    .trim()
+    .regex(/^[A-Za-z0-9_-]{43}$/, 'ticket must be 32 bytes of base64url');
+/** `POST /auth/email/verify/start` */
+exports.emailVerificationStartRequestSchema = zod_1.z
+    .object({ purpose: zod_1.z.literal('signup'), email: exports.emailAddressSchema })
+    .strict();
+exports.emailVerificationStartResponseSchema = zod_1.z.object({
+    verificationId: zod_1.z.string().min(1).max(64),
+    expiresAt: zod_1.z.number().int().positive(),
+});
+/** `POST /auth/email/verify/confirm` */
+exports.emailVerificationConfirmRequestSchema = zod_1.z
+    .object({
+    verificationId: zod_1.z.string().trim().min(1).max(64),
+    code: zod_1.z
+        .string()
+        .trim()
+        .regex(new RegExp(`^\\d{${exports.EMAIL_CODE_LENGTH}}$`), `code must be ${exports.EMAIL_CODE_LENGTH} digits`),
+})
+    .strict();
+exports.emailVerificationConfirmResponseSchema = zod_1.z.object({
+    ticket: exports.emailTicketSchema,
+    expiresAt: zod_1.z.number().int().positive(),
+});
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+exports.EMAIL_VERIFICATION_ERROR_CODES = {
+    /** The code is wrong, or its verification expired or was spent. */
+    codeInvalid: 'EMAIL_CODE_INVALID',
+    /** Too many wrong codes: request a new one. */
+    tooManyAttempts: 'EMAIL_CODE_TOO_MANY_ATTEMPTS',
+    /** The ticket is unknown, expired, spent, or for another email or purpose. */
+    ticketInvalid: 'EMAIL_TICKET_INVALID',
+    /** A sign-up without a confirmed email. */
+    ticketRequired: 'EMAIL_TICKET_REQUIRED',
+    /** This server cannot send mail. */
+    unavailable: 'EMAIL_UNAVAILABLE',
+};

package/dist/cjs/deviceBoot.js

@@ -5,8 +5,8 @@
  * SINGLE SOURCE OF TRUTH for the first-party login result (the session arm). The
  * API validates its OUTPUT against this schema; every consumer (`@oxy.so/core`'s
  * auth mixin) validates its INPUT against the same definition, so producer and
- * consumers cannot drift. Sign-in is passkey (WebAuthn) or Commons handoff —
- * password and 2FA were removed, so the only outcome is a completed session.
+ * consumers cannot drift. This is the session arm every sign-in
+ * ends in (email code or link, password, authenticator, Commons handoff).
  *
  * The device transport is `deviceId` + `deviceSecret` + `POST /session/device/token`
  * (see `deviceSession.ts`). The legacy cookie/bootstrap/refresh-family lanes were

package/dist/cjs/deviceSession.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deviceBackgroundTokenResponseSchema = exports.deviceBackgroundTokenRequestSchema = exports.deviceBackgroundCredentialResponseSchema = exports.sessionAccountsChangedEventSchema = exports.sessionAccountsChangedReasonSchema = exports.SESSION_ACCOUNTS_CHANGED_EVENT = exports.deviceTokenMintResponseSchema = exports.deviceTokenMintRequestSchema = exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = void 0;
+exports.deviceJoinResponseSchema = exports.deviceJoinRequestSchema = exports.deviceJoinCodeResponseSchema = exports.deviceJoinCodeRequestSchema = exports.deviceRegisterResponseSchema = exports.deviceProofSchema = exports.deviceBackgroundTokenResponseSchema = exports.deviceBackgroundTokenRequestSchema = exports.deviceBackgroundCredentialResponseSchema = exports.sessionAccountsChangedEventSchema = exports.sessionAccountsChangedReasonSchema = exports.SESSION_ACCOUNTS_CHANGED_EVENT = exports.deviceTokenMintResponseSchema = exports.deviceTokenMintRequestSchema = exports.deviceSessionSyncSchema = exports.activeTokenSchema = exports.deviceSessionStateSchema = exports.sessionAccountSchema = void 0;
 const zod_1 = require("zod");
 exports.sessionAccountSchema = zod_1.z.object({
     accountId: zod_1.z.string(),
@@ -29,9 +29,10 @@ exports.deviceSessionSyncSchema = zod_1.z.object({
 /**
  * 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.
+ * possession of the secret IS the proof of device ownership. The server looks
+ * `sha256(deviceSecret)` up among the device's holder credentials (one per app
+ * or origin that joined the shared DeviceSession) 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),
@@ -51,8 +52,8 @@ exports.deviceTokenMintRequestSchema = zod_1.z.object({
  * 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.
+ * and the projected device-session state. Nothing rotates: each sign-in issues
+ * a NEW holder credential and leaves the others valid.
  */
 exports.deviceTokenMintResponseSchema = zod_1.z.object({
     accessToken: zod_1.z.string(),
@@ -110,12 +111,11 @@ exports.sessionAccountsChangedEventSchema = zod_1.z.object({
  * 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.
+ * Deliberately a SEPARATE credential from the holder `deviceSecret`: that one
+ * is device-wide and mints for whichever account is active, while this one is
+ * bound to ONE account and expires, so a widget worker never holds a
+ * credential that reaches every account on the device. Background code is its
+ * sole writer and never touches 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
@@ -138,10 +138,10 @@ exports.deviceBackgroundCredentialResponseSchema = zod_1.z.object({
  * 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.
+ * Like that mint this one NEVER rotates the presented secret, and it carries
+ * no `next…` field at all, so background code interrupted anywhere between
+ * request and response leaves the credential intact and usable on its next
+ * run.
  */
 exports.deviceBackgroundTokenRequestSchema = zod_1.z.object({
     deviceId: zod_1.z.string().min(1),
@@ -162,3 +162,60 @@ exports.deviceBackgroundTokenResponseSchema = zod_1.z.object({
     expiresAt: zod_1.z.string(),
     accountId: zod_1.z.string().min(1),
 });
+/* -------------------------------------------------------------------------- */
+/*  The browser bridge — joining the browser's DeviceSession (ADR 0029 D2)    */
+/* -------------------------------------------------------------------------- */
+/**
+ * Proof that the caller holds a device: the `deviceId` it stored first-party and
+ * one of that device's holder secrets. Sent with `POST /session/device/join-code`
+ * and, optionally, with a sign-in (`POST /auth/session/claim`, the email,
+ * password and second-factor sign-ins, `POST /auth/signup`), where
+ * a valid proof puts the new session on THAT device so every app holding it sees
+ * the account. An invalid proof on a sign-in is ignored, never an error.
+ */
+exports.deviceProofSchema = zod_1.z.object({
+    deviceId: zod_1.z.string().min(1).max(128),
+    deviceSecret: zod_1.z.string().min(1).max(256),
+});
+/**
+ * `POST /session/device/register` — auth.oxy.so only. No body. A new, empty
+ * DeviceSession with a server-chosen `deviceId` and ONE holder credential for
+ * auth.oxy.so. The raw secret is returned exactly once.
+ */
+exports.deviceRegisterResponseSchema = zod_1.z.object({
+    deviceId: zod_1.z.string().min(1),
+    deviceSecret: zod_1.z.string().min(1),
+});
+/** PKCE S256 challenge: base64url of a SHA-256 digest (43 characters). */
+const pkceS256ChallengeSchema = zod_1.z.string().regex(/^[A-Za-z0-9_-]{43}$/);
+/**
+ * `POST /session/device/join-code` — auth.oxy.so only (the bridge window). Proves
+ * auth.oxy.so's device and asks for a one-use code an official app redeems to
+ * join it. The code is bound to the application (`clientId`), its exact
+ * registered `redirectUri` and the app's PKCE challenge, and lives about a
+ * minute.
+ */
+exports.deviceJoinCodeRequestSchema = exports.deviceProofSchema.extend({
+    clientId: zod_1.z.string().min(1).max(256),
+    redirectUri: zod_1.z.string().url().max(2048),
+    codeChallenge: pkceS256ChallengeSchema,
+    codeChallengeMethod: zod_1.z.literal('S256'),
+});
+exports.deviceJoinCodeResponseSchema = zod_1.z.object({
+    code: zod_1.z.string().min(1),
+    /** Seconds until the code expires. */
+    expiresIn: zod_1.z.number().int().positive(),
+});
+/**
+ * `POST /session/device/join` — called by the app's own origin with the code the
+ * bridge window posted to it and the PKCE verifier only the app holds. Returns a
+ * NEW holder credential for the browser's device; the app then mints through the
+ * ordinary `POST /session/device/token`.
+ */
+exports.deviceJoinRequestSchema = zod_1.z.object({
+    code: zod_1.z.string().min(1).max(256),
+    codeVerifier: zod_1.z.string().min(43).max(128).regex(/^[A-Za-z0-9._~-]+$/),
+    clientId: zod_1.z.string().min(1).max(256),
+    redirectUri: zod_1.z.string().url().max(2048),
+});
+exports.deviceJoinResponseSchema = exports.deviceRegisterResponseSchema;

package/dist/cjs/identity.js

@@ -210,11 +210,9 @@ exports.domainVerificationInstructionsSchema = zod_1.z.object({
     }),
 });
 exports.authMethodEntrySchema = zod_1.z.object({
-    type: zod_1.z.enum(['identity', 'webauthn']),
+    type: zod_1.z.literal('identity'),
     linkedAt: zod_1.z.union([zod_1.z.string(), zod_1.z.date()]),
     verificationMethodId: zod_1.z.string().optional(),
-    credentialId: zod_1.z.string().optional(),
-    name: zod_1.z.string().optional(),
 });
 exports.authMethodsResponseSchema = zod_1.z.object({
     did: zod_1.z.string(),

package/dist/cjs/identityLink.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityLinkCompleteRequestSchema = exports.identityLinkProofRequestSchema = exports.identityLinkStateSchema = exports.identityLinkCreateResponseSchema = exports.identityLinkIdSchema = exports.IDENTITY_LINK_QR_PREFIX = exports.IDENTITY_LINK_STATUSES = void 0;
+exports.buildIdentityLinkQrPayload = buildIdentityLinkQrPayload;
+exports.parseIdentityLinkQrPayload = parseIdentityLinkQrPayload;
+/**
+ * Linking Commons to an account without a key (ADR 0029 D3) — the two-device
+ * relay.
+ *
+ * An account without a key links a Commons root once, and becomes
+ * self-custodied: its email is deleted and its phrase in Commons is how it gets
+ * back in. The authority is the same as `POST /auth/link` (ADR 0024 D8): a root
+ * proof (`link_identity`) by the key Commons holds over a one-use challenge,
+ * and the account's own confirmation — a code just sent to its email (plus its
+ * authenticator code when it has one). Only the transport is new, because the
+ * two factors live on two devices:
+ *
+ *   1. The signed-in account (the "Link Commons" panel of `@oxy.so/services`)
+ *      opens a link request → `{ linkId, challenge }`, shown as a QR
+ *      (`oxycommons://link?id=…&c=…`).
+ *   2. Commons scans it, reads the request (the account's id and username),
+ *      signs the root proof over the challenge and posts it with its key.
+ *   3. Both screens show the same 6-digit code, derived from the link id and
+ *      that key (`deriveIdentityLinkCode` in `@oxy.so/core`); the person checks
+ *      they match, so a photographed QR cannot slip another key in.
+ *   4. The panel completes with the email code: the account gains the root,
+ *      loses the email, and Commons signs in with it.
+ *
+ * The server stores only the challenge's hash; the challenge travels in the QR.
+ */
+const zod_1 = require("zod");
+const identityProof_1 = require("./identityProof");
+const signIn_1 = require("./signIn");
+exports.IDENTITY_LINK_STATUSES = ['pending', 'signed', 'completed', 'cancelled'];
+/** The scheme and host Commons routes a link QR to. */
+exports.IDENTITY_LINK_QR_PREFIX = 'oxycommons://link';
+const LINK_ID = /^[0-9a-f]{32}$/;
+const CHALLENGE = /^[0-9a-f]{64}$/;
+exports.identityLinkIdSchema = zod_1.z.string().trim().regex(LINK_ID, 'linkId must be 32 lowercase hex characters');
+/** The QR auth.oxy.so shows: the request's id and the challenge Commons signs. */
+function buildIdentityLinkQrPayload(linkId, challenge) {
+    return `${exports.IDENTITY_LINK_QR_PREFIX}?id=${linkId}&c=${challenge}`;
+}
+/** The request a scanned code names, or `null` for anything that is not a link QR. */
+function parseIdentityLinkQrPayload(raw) {
+    const value = raw.trim();
+    if (!value.startsWith(`${exports.IDENTITY_LINK_QR_PREFIX}?`))
+        return null;
+    // Parsed by hand: React Native's `URLSearchParams` does not implement `get`.
+    const params = new Map();
+    for (const pair of value.slice(exports.IDENTITY_LINK_QR_PREFIX.length + 1).split('&')) {
+        const separator = pair.indexOf('=');
+        if (separator > 0)
+            params.set(pair.slice(0, separator), pair.slice(separator + 1));
+    }
+    const linkId = params.get('id') ?? '';
+    const challenge = params.get('c') ?? '';
+    if (!LINK_ID.test(linkId) || !CHALLENGE.test(challenge))
+        return null;
+    return { linkId, challenge };
+}
+exports.identityLinkCreateResponseSchema = zod_1.z.object({
+    linkId: exports.identityLinkIdSchema,
+    challenge: zod_1.z.string().regex(CHALLENGE),
+    expiresAt: zod_1.z.number().int().positive(),
+    qrPayload: zod_1.z.string().startsWith(exports.IDENTITY_LINK_QR_PREFIX),
+});
+exports.identityLinkStateSchema = zod_1.z.object({
+    status: zod_1.z.enum(exports.IDENTITY_LINK_STATUSES),
+    userId: zod_1.z.string().min(1),
+    username: zod_1.z.string().nullable(),
+    publicKey: zod_1.z.string().nullable(),
+    audience: zod_1.z.string().min(1),
+    expiresAt: zod_1.z.number().int().positive(),
+});
+/** `POST /identity/link/:linkId/proof` — from Commons, no bearer. */
+exports.identityLinkProofRequestSchema = zod_1.z
+    .object({
+    publicKey: zod_1.z
+        .string()
+        .trim()
+        .toLowerCase()
+        .regex(/^04[0-9a-f]{128}$/, 'publicKey must be an uncompressed secp256k1 key'),
+    proof: identityProof_1.identityProofSchema,
+})
+    .strict();
+/**
+ * `POST /identity/link/:linkId/complete` — the account's own confirmation: a
+ * code just sent to its email for this link (`reauth`, plus its authenticator
+ * code when it has one).
+ */
+exports.identityLinkCompleteRequestSchema = zod_1.z.object({ reauth: signIn_1.emailReauthProofSchema }).strict();

package/dist/cjs/identityProof.js

@@ -32,26 +32,12 @@ exports.IDENTITY_PROOF_CHALLENGE_TTL_MS = 5 * 60 * 1000;
  * action and spent only by a proof for that action.
  */
 exports.IDENTITY_PROOF_ACTIONS = {
-    /** A keyless account's FIRST root, stored with its web envelope. */
-    establish: 'web_envelope_establish',
-    /** Replace the web envelope (add or remove a wrap, re-seal). */
-    put: 'web_envelope_put',
-    /** Record that the recovery material is written down. */
-    phraseConfirmed: 'web_envelope_phrase_confirmed',
-    /** Record that the recovery material re-derived the root. */
-    recoveryVerified: 'web_envelope_recovery_verified',
-    /** Remove the web holder. */
-    delete: 'web_envelope_delete',
-    /** Link a keyless account's first root without a web envelope (`POST /auth/link`). */
+    /**
+     * Link Commons' root to an account that has none (`POST /auth/link`).
+     * The account becomes self-custodied and its email is deleted
+     * (ADR 0029 D3).
+     */
     link: 'link_identity',
-    /** Create a personal account together with its root (passkey sign-up). */
-    enroll: 'enroll_identity',
-    /** Prove the root to start signed-out recovery. */
-    recoverStart: 'recover_account_start',
-    /** Bind the new passkey and envelope when completing signed-out recovery. */
-    recoverComplete: 'recover_account_complete',
-    /** Seal the root for the Commons device that joined a move (payload: move id + sealed bytes). */
-    moveSeal: 'identity_move_seal',
 };
 exports.IDENTITY_PROOF_ACTION_VALUES = Object.values(exports.IDENTITY_PROOF_ACTIONS);
 const HEX_DIGEST = /^[0-9a-f]{64}$/;
@@ -144,21 +130,12 @@ exports.identityProofChallengeResponseSchema = zod_1.z.object({
  */
 exports.IDENTITY_ERROR_CODES = {
     proofInvalid: 'IDENTITY_PROOF_INVALID',
-    revisionConflict: 'IDENTITY_ENVELOPE_REVISION_CONFLICT',
     rootAlreadyLinked: 'IDENTITY_ROOT_ALREADY_LINKED',
     rootLinkedElsewhere: 'IDENTITY_ROOT_LINKED_ELSEWHERE',
-    noRoot: 'IDENTITY_NO_ROOT',
     freshFactorRequired: 'IDENTITY_FRESH_FACTOR_REQUIRED',
-    lastWebHolder: 'IDENTITY_LAST_WEB_HOLDER',
-    enrollmentRequired: 'IDENTITY_ENROLLMENT_REQUIRED',
-    enrollmentInvalid: 'IDENTITY_ENROLLMENT_INVALID',
     notPersonal: 'IDENTITY_NOT_PERSONAL_ACCOUNT',
-    recoveryFailed: 'IDENTITY_RECOVERY_FAILED',
 };
 exports.identityRootStatusSchema = zod_1.z.object({
     rootLinked: zod_1.z.boolean(),
-    webHolder: zod_1.z.object({ passkeys: zod_1.z.number().int().nonnegative(), verifiedPasskeys: zod_1.z.number().int().nonnegative() }).nullable(),
-    hasPhrase: zod_1.z.boolean().nullable(),
-    phraseConfirmedAt: zod_1.z.string().datetime().nullable(),
-    recoveryVerifiedAt: zod_1.z.string().datetime().nullable(),
+    recoveryEmail: zod_1.z.string().nullable(),
 });