@oxy.so/contracts 2.1.0 → 2.2.0

package/dist/esm/accountEmail.js

@@ -0,0 +1,80 @@
+/**
+ * Recovery email contracts (ADR 0029 D3).
+ *
+ * A web account is a username, a passkey and a recovery email. 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 /webauthn/register/verify` create the
+ *   account with that email;
+ * - `recovery`: the person names their username or email, the code goes to the
+ *   account's recovery email, and the ticket lets them register a new passkey
+ *   for that account.
+ *
+ * `start` answers the same whether or not an account exists, so neither purpose
+ * tells anyone which emails or usernames have an Oxy account. An account with a
+ * Commons key has no recovery email: it recovers in Commons.
+ */
+import { z } from 'zod';
+export const EMAIL_VERIFICATION_PURPOSES = ['signup', 'recovery'];
+/** Digits in a code. */
+export const EMAIL_CODE_LENGTH = 6;
+/** How long a code can be confirmed. */
+export const EMAIL_CODE_TTL_MS = 10 * 60 * 1000;
+/** Wrong codes before a verification is spent and a new code is needed. */
+export const EMAIL_CODE_MAX_ATTEMPTS = 5;
+/** How long a confirmed code's ticket can be spent. */
+export const EMAIL_TICKET_TTL_MS = 15 * 60 * 1000;
+/** An email address as the API stores it: trimmed and lowercase. */
+export const emailAddressSchema = z.string().trim().toLowerCase().min(3).max(254).email();
+/** An opaque one-use ticket (32 random bytes, base64url). */
+export const emailTicketSchema = z
+    .string()
+    .trim()
+    .regex(/^[A-Za-z0-9_-]{43}$/, 'ticket must be 32 bytes of base64url');
+/** `POST /auth/email/verify/start` */
+export const emailVerificationStartRequestSchema = z.discriminatedUnion('purpose', [
+    z.object({ purpose: z.literal('signup'), email: emailAddressSchema }).strict(),
+    z
+        .object({
+        purpose: z.literal('recovery'),
+        /** The account's username, or its recovery email. */
+        identifier: z.string().trim().min(1).max(254),
+    })
+        .strict(),
+]);
+export const emailVerificationStartResponseSchema = z.object({
+    verificationId: z.string().min(1).max(64),
+    expiresAt: z.number().int().positive(),
+});
+/** `POST /auth/email/verify/confirm` */
+export const emailVerificationConfirmRequestSchema = z
+    .object({
+    verificationId: z.string().trim().min(1).max(64),
+    code: z
+        .string()
+        .trim()
+        .regex(new RegExp(`^\\d{${EMAIL_CODE_LENGTH}}$`), `code must be ${EMAIL_CODE_LENGTH} digits`),
+})
+    .strict();
+export const emailVerificationConfirmResponseSchema = z.object({
+    ticket: emailTicketSchema,
+    expiresAt: z.number().int().positive(),
+    username: z.string().nullable(),
+});
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+export const 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 recovery email. */
+    ticketRequired: 'EMAIL_TICKET_REQUIRED',
+    /** This server cannot send mail. */
+    unavailable: 'EMAIL_UNAVAILABLE',
+};

package/dist/esm/identityLink.js

@@ -0,0 +1,84 @@
+/**
+ * Linking Commons to a passkey account (ADR 0029 D3) — the two-device relay.
+ *
+ * A passkey account links a Commons root once, and becomes self-custodied: its
+ * recovery 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, and a fresh assertion by one of
+ * the account's passkeys over the SAME one-use challenge. Only the transport is
+ * new, because the two factors live on two devices:
+ *
+ *   1. auth.oxy.so (signed in) 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. auth.oxy.so asserts the passkey over the challenge and completes: 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.
+ */
+import { z } from 'zod';
+import { identityProofSchema } from './identityProof.js';
+import { webauthnAssertionResponseSchema } from './webauthn.js';
+export const IDENTITY_LINK_STATUSES = ['pending', 'signed', 'completed', 'cancelled'];
+/** The scheme and host Commons routes a link QR to. */
+export const IDENTITY_LINK_QR_PREFIX = 'oxycommons://link';
+const LINK_ID = /^[0-9a-f]{32}$/;
+const CHALLENGE = /^[0-9a-f]{64}$/;
+export const identityLinkIdSchema = 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. */
+export function buildIdentityLinkQrPayload(linkId, challenge) {
+    return `${IDENTITY_LINK_QR_PREFIX}?id=${linkId}&c=${challenge}`;
+}
+/** The request a scanned code names, or `null` for anything that is not a link QR. */
+export function parseIdentityLinkQrPayload(raw) {
+    const value = raw.trim();
+    if (!value.startsWith(`${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(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 };
+}
+export const identityLinkCreateResponseSchema = z.object({
+    linkId: identityLinkIdSchema,
+    challenge: z.string().regex(CHALLENGE),
+    expiresAt: z.number().int().positive(),
+    qrPayload: z.string().startsWith(IDENTITY_LINK_QR_PREFIX),
+});
+export const identityLinkStateSchema = z.object({
+    status: z.enum(IDENTITY_LINK_STATUSES),
+    userId: z.string().min(1),
+    username: z.string().nullable(),
+    publicKey: z.string().nullable(),
+    audience: z.string().min(1),
+    expiresAt: z.number().int().positive(),
+});
+/** `POST /identity/link/:linkId/proof` — from Commons, no bearer. */
+export const identityLinkProofRequestSchema = z
+    .object({
+    publicKey: z
+        .string()
+        .trim()
+        .toLowerCase()
+        .regex(/^04[0-9a-f]{128}$/, 'publicKey must be an uncompressed secp256k1 key'),
+    proof: identityProofSchema,
+})
+    .strict();
+/** `POST /identity/link/:linkId/options` — WebAuthn request options over the challenge. */
+export const identityLinkOptionsRequestSchema = z
+    .object({ challenge: z.string().trim().regex(CHALLENGE, 'challenge must be 64 lowercase hex characters') })
+    .strict();
+/** `POST /identity/link/:linkId/complete` — the passkey assertion over the challenge. */
+export const identityLinkCompleteRequestSchema = z.object({ assertion: webauthnAssertionResponseSchema }).strict();

package/dist/esm/identityProof.js

@@ -27,26 +27,12 @@ export const IDENTITY_PROOF_CHALLENGE_TTL_MS = 5 * 60 * 1000;
  * action and spent only by a proof for that action.
  */
 export const 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 a passkey account that has none (`POST /auth/link`).
+     * The account becomes self-custodied and its recovery 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',
 };
 export const IDENTITY_PROOF_ACTION_VALUES = Object.values(IDENTITY_PROOF_ACTIONS);
 const HEX_DIGEST = /^[0-9a-f]{64}$/;
@@ -139,21 +125,12 @@ export const identityProofChallengeResponseSchema = z.object({
  */
 export const 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',
 };
 export const identityRootStatusSchema = z.object({
     rootLinked: z.boolean(),
-    webHolder: z.object({ passkeys: z.number().int().nonnegative(), verifiedPasskeys: z.number().int().nonnegative() }).nullable(),
-    hasPhrase: z.boolean().nullable(),
-    phraseConfirmedAt: z.string().datetime().nullable(),
-    recoveryVerifiedAt: z.string().datetime().nullable(),
+    recoveryEmail: z.string().nullable(),
 });

package/dist/esm/index.js

@@ -80,18 +80,9 @@ export {
 // Schemas — encrypted off-device identity backup (b3 Feature 1)
 backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery.js';
 export { 
-// Schemas — web identity carrier (one identity, two carriers)
-WEB_IDENTITY_ENVELOPE_VERSION, WEB_IDENTITY_SECRET_KINDS, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webauthnRpIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityHolderSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofFieldsSchema, webIdentityEnvelopeActionSchema, webIdentityEnvelopePutSchema, webauthnAssertionResponseSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier.js';
-export { 
 // Identity proofs (ADR 0024 D7) — the one signed format for root operations
 IDENTITY_PROOF_VERSION, IDENTITY_PROOF_DOMAIN, IDENTITY_PROOF_AUDIENCE, IDENTITY_PROOF_CHALLENGE_TTL_MS, IDENTITY_PROOF_ACTIONS, IDENTITY_PROOF_ACTION_VALUES, IDENTITY_ERROR_CODES, canonicalJson, buildIdentityProofMessage, identityProofSchema, identityProofChallengeRequestSchema, identityProofChallengeResponseSchema, identityRootStatusSchema, } from './identityProof.js';
 export { 
-// Signed-out recovery (ADR 0024 D5)
-IDENTITY_RECOVERY_TTL_MS, identityRecoveryChallengeResponseSchema, identityRecoveryStartRequestSchema, identityRecoveryCompleteRequestSchema, } from './identityRecovery.js';
-export { 
-// Schemas — moving a web identity into Commons
-IDENTITY_MOVE_TTL_MS, IDENTITY_MOVE_STATUSES, IDENTITY_MOVE_QR_PREFIX, identityMoveRevealRequestSchema, buildMoveCommitmentInput, buildMoveSasInput, buildMoveSealPayload, buildMoveCiphertextDigestInput, buildMoveReceiptMessage, identityMoveIdSchema, identityMoveEphemeralKeySchema, identityMoveCreateRequestSchema, identityMoveCreateResponseSchema, identityMoveJoinRequestSchema, identityMoveSealRequestSchema, identityMoveReceiptRequestSchema, identityMoveStateSchema, } from './identityMove.js';
-export { 
 // Shared primitives
 updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, 
 // Assets: init + complete
@@ -104,7 +95,13 @@ updateSchema, createUpdateResponseSchema, rollbackToEmbeddedEntrySchema, channel
 rollbackRequestSchema, rollbackToEmbeddedRequestSchema, promoteRequestSchema, updateRolloutPatchSchema, } from './updates.js';
 export { 
 // Schemas
-webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn.js';
+webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, webauthnCredentialIdSchema, webauthnAssertionResponseSchema, } from './webauthn.js';
+export { 
+// Recovery email of a passkey account (ADR 0029 D3)
+EMAIL_VERIFICATION_PURPOSES, EMAIL_CODE_LENGTH, EMAIL_CODE_TTL_MS, EMAIL_CODE_MAX_ATTEMPTS, EMAIL_TICKET_TTL_MS, EMAIL_VERIFICATION_ERROR_CODES, emailAddressSchema, emailTicketSchema, emailVerificationStartRequestSchema, emailVerificationStartResponseSchema, emailVerificationConfirmRequestSchema, emailVerificationConfirmResponseSchema, } from './accountEmail.js';
+export { 
+// Linking Commons to a passkey account (ADR 0029 D3)
+IDENTITY_LINK_STATUSES, IDENTITY_LINK_QR_PREFIX, identityLinkIdSchema, buildIdentityLinkQrPayload, parseIdentityLinkQrPayload, identityLinkCreateResponseSchema, identityLinkStateSchema, identityLinkProofRequestSchema, identityLinkOptionsRequestSchema, identityLinkCompleteRequestSchema, } from './identityLink.js';
 export { 
 // Schemas — transparency log (checkpoints + inclusion proofs)
 transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency.js';

package/dist/esm/webauthn.js

@@ -11,8 +11,37 @@
  * create a second, drift-prone definition of a shape we do not own.
  */
 import { z } from 'zod';
-import { identityProofSchema } from './identityProof.js';
-import { webIdentityEnvelopeSchema } from './webIdentityCarrier.js';
+import { emailAddressSchema, emailTicketSchema } from './accountEmail.js';
+/** A WebAuthn credential id, base64url as the browser reports it. */
+export const webauthnCredentialIdSchema = z
+    .string()
+    .trim()
+    .min(16)
+    .max(1024)
+    .regex(/^[A-Za-z0-9_-]+$/, 'credentialId must be base64url');
+/**
+ * A WebAuthn assertion by one of the account's EXISTING passkeys over a server
+ * challenge — the fresh use of the factor the account already has (linking
+ * Commons to a passkey account, deleting a passkey account). The API verifies
+ * it with `@simplewebauthn/server`; this only bounds its shape.
+ */
+export const webauthnAssertionResponseSchema = z
+    .object({
+    id: webauthnCredentialIdSchema,
+    rawId: z.string().min(1).max(2048),
+    type: z.literal('public-key'),
+    response: z
+        .object({
+        clientDataJSON: z.string().min(1).max(8192),
+        authenticatorData: z.string().min(1).max(8192),
+        signature: z.string().min(1).max(2048),
+        userHandle: z.string().max(2048).optional(),
+    })
+        .passthrough(),
+    clientExtensionResults: z.record(z.string(), z.unknown()).optional(),
+    authenticatorAttachment: z.string().optional(),
+})
+    .passthrough();
 /**
  * Device-session options shared by every first-party sign-in body
  * (`deviceName`/`deviceFingerprint`). Mirrors what
@@ -33,13 +62,16 @@ const deviceSessionEnvelope = {
     deviceFingerprint: z.string().trim().min(1).max(256).optional(),
 };
 /**
- * `POST /webauthn/register/options` — request registration options. With a bearer
- * token the caller links a passkey to their signed-in account and `username` is
- * ignored; without one it is a prospective signup and `username` is the desired
- * (not-yet-created) handle.
+ * `POST /webauthn/register/options` — request registration options. Three flows:
+ *
+ * - a bearer: the caller adds a passkey to their signed-in account;
+ * - `recoveryTicket` (no bearer): a new passkey for the account a recovery code
+ *   was confirmed for (`POST /auth/email/verify/confirm`, purpose `recovery`);
+ * - `username` (no bearer): a prospective sign-up; the handle is not created yet.
  */
 export const webauthnRegisterOptionsRequestSchema = z.object({
     username: z.string().trim().min(1).max(60).optional(),
+    recoveryTicket: emailTicketSchema.optional(),
 });
 /**
  * `POST /webauthn/login/options` — request authentication options. When
@@ -53,23 +85,20 @@ export const webauthnLoginOptionsRequestSchema = z.object({
 /**
  * `POST /webauthn/register/verify` — the outer envelope. The browser
  * `RegistrationResponseJSON` travels alongside these fields under `response` and
- * is validated by `@simplewebauthn/server`, not here. `username` is required only
- * for the prospective-signup branch (no bearer); the linking branch ignores it.
+ * is validated by `@simplewebauthn/server`, not here.
+ *
+ * - Sign-up (no bearer, ADR 0029 D3): `username`, the recovery `email` and the
+ *   `emailTicket` its code was confirmed with. The account is created with the
+ *   passkey and that verified email, and no key.
+ * - Recovery (no bearer): `recoveryTicket`; the passkey is added to its account
+ *   and a session minted.
+ * - A bearer: the passkey is added to the signed-in account.
  */
 export const webauthnRegisterVerifyRequestSchema = z.object({
     username: z.string().trim().min(1).max(60).optional(),
-    /**
-     * Sign-up only (ADR 0024 D4): the account's root, created on the holder BEFORE
-     * this request — sealed under the passkey being registered — and a root proof
-     * (`enroll_identity`) whose challenge is the registration challenge. The
-     * account, passkey, root and envelope are then created in one transaction.
-     */
-    identity: z
-        .object({
-        envelope: webIdentityEnvelopeSchema,
-        proof: identityProofSchema,
-    })
-        .optional(),
+    email: emailAddressSchema.optional(),
+    emailTicket: emailTicketSchema.optional(),
+    recoveryTicket: emailTicketSchema.optional(),
     ...deviceSessionEnvelope,
 });
 /**