@oxy.so/contracts 2.1.0 → 2.2.0

package/dist/types/accountEmail.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 declare const EMAIL_VERIFICATION_PURPOSES: readonly ["signup", "recovery"];
+export type EmailVerificationPurpose = (typeof EMAIL_VERIFICATION_PURPOSES)[number];
+/** Digits in a code. */
+export declare const EMAIL_CODE_LENGTH = 6;
+/** How long a code can be confirmed. */
+export declare const EMAIL_CODE_TTL_MS: number;
+/** Wrong codes before a verification is spent and a new code is needed. */
+export declare const EMAIL_CODE_MAX_ATTEMPTS = 5;
+/** How long a confirmed code's ticket can be spent. */
+export declare const EMAIL_TICKET_TTL_MS: number;
+/** An email address as the API stores it: trimmed and lowercase. */
+export declare const emailAddressSchema: z.ZodString;
+/** An opaque one-use ticket (32 random bytes, base64url). */
+export declare const emailTicketSchema: z.ZodString;
+/** `POST /auth/email/verify/start` */
+export declare const emailVerificationStartRequestSchema: z.ZodDiscriminatedUnion<"purpose", [z.ZodObject<{
+    purpose: z.ZodLiteral<"signup">;
+    email: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    purpose: "signup";
+    email: string;
+}, {
+    purpose: "signup";
+    email: string;
+}>, z.ZodObject<{
+    purpose: z.ZodLiteral<"recovery">;
+    /** The account's username, or its recovery email. */
+    identifier: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    purpose: "recovery";
+    identifier: string;
+}, {
+    purpose: "recovery";
+    identifier: string;
+}>]>;
+export type EmailVerificationStartRequest = z.infer<typeof emailVerificationStartRequestSchema>;
+export interface EmailVerificationStartResponse {
+    /** Names this verification in `confirm`. Returned whether or not a code was sent. */
+    verificationId: string;
+    /** Unix milliseconds after which the code is refused. */
+    expiresAt: number;
+}
+export declare const emailVerificationStartResponseSchema: z.ZodType<EmailVerificationStartResponse>;
+/** `POST /auth/email/verify/confirm` */
+export declare const emailVerificationConfirmRequestSchema: z.ZodObject<{
+    verificationId: z.ZodString;
+    code: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    verificationId: string;
+}, {
+    code: string;
+    verificationId: string;
+}>;
+export type EmailVerificationConfirmRequest = z.infer<typeof emailVerificationConfirmRequestSchema>;
+export interface EmailVerificationConfirmResponse {
+    ticket: string;
+    /** Unix milliseconds after which the ticket is refused. */
+    expiresAt: number;
+    /** Recovery only: the account the ticket recovers. `null` for sign-up. */
+    username: string | null;
+}
+export declare const emailVerificationConfirmResponseSchema: z.ZodType<EmailVerificationConfirmResponse>;
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+export declare const EMAIL_VERIFICATION_ERROR_CODES: {
+    /** The code is wrong, or its verification expired or was spent. */
+    readonly codeInvalid: "EMAIL_CODE_INVALID";
+    /** Too many wrong codes: request a new one. */
+    readonly tooManyAttempts: "EMAIL_CODE_TOO_MANY_ATTEMPTS";
+    /** The ticket is unknown, expired, spent, or for another email or purpose. */
+    readonly ticketInvalid: "EMAIL_TICKET_INVALID";
+    /** A sign-up without a confirmed recovery email. */
+    readonly ticketRequired: "EMAIL_TICKET_REQUIRED";
+    /** This server cannot send mail. */
+    readonly unavailable: "EMAIL_UNAVAILABLE";
+};
+export type EmailVerificationErrorCode = (typeof EMAIL_VERIFICATION_ERROR_CODES)[keyof typeof EMAIL_VERIFICATION_ERROR_CODES];

package/dist/types/accountGraph.d.ts

@@ -315,8 +315,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
      */
     isPrivateAccount: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
-    kind: "bot" | "organization" | "project" | "channel";
     username: string;
+    kind: "bot" | "organization" | "project" | "channel";
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -330,8 +330,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }, {
-    kind: "bot" | "organization" | "project" | "channel";
     username: string;
+    kind: "bot" | "organization" | "project" | "channel";
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -345,8 +345,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }>, {
-    kind: "bot" | "organization" | "project" | "channel";
     username: string;
+    kind: "bot" | "organization" | "project" | "channel";
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;
@@ -360,8 +360,8 @@ export declare const createAccountRequestSchema: z.ZodEffects<z.ZodObject<{
     accountCategories?: ("security" | "news" | "politics" | "business" | "startup" | "finance" | "crypto" | "marketplace" | "retail" | "real_estate" | "agency" | "landlord" | "cooperative" | "architecture" | "technology" | "software" | "ai" | "automation" | "science" | "education" | "books" | "health" | "fitness" | "sports" | "gaming" | "music" | "film" | "podcast" | "art" | "photography" | "comedy" | "food" | "travel" | "fashion" | "home_garden" | "diy" | "automotive" | "animals" | "family" | "nonprofit" | "government" | "community" | "activism" | "environment" | "religion" | "other")[] | undefined;
     isPrivateAccount?: boolean | undefined;
 }, {
-    kind: "bot" | "organization" | "project" | "channel";
     username: string;
+    kind: "bot" | "organization" | "project" | "channel";
     parentAccountId?: string | undefined;
     name?: {
         first?: string | undefined;

package/dist/types/agency.d.ts

@@ -190,6 +190,7 @@ export declare const delegationGrantSchema: z.ZodObject<{
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, "strict", z.ZodTypeAny, {
+    expiresAt: string | null;
     ownerAccountId: string;
     id: string;
     actor: {
@@ -223,11 +224,11 @@ export declare const delegationGrantSchema: z.ZodObject<{
     }[];
     maximumAutonomy: "read_only" | "draft" | "execute_on_request" | "autonomous";
     canRedelegate: boolean;
-    expiresAt: string | null;
     revokedAt: string | null;
     createdAt: string;
     updatedAt: string;
 }, {
+    expiresAt: string | null;
     ownerAccountId: string;
     id: string;
     actor: {
@@ -251,7 +252,6 @@ export declare const delegationGrantSchema: z.ZodObject<{
     capabilityPackages: ("security" | "finance" | "read" | "create" | "publish" | "communicate" | "administer" | "delegate")[];
     capabilities: string[];
     maximumAutonomy: "read_only" | "draft" | "execute_on_request" | "autonomous";
-    expiresAt: string | null;
     createdAt: string;
     updatedAt: string;
     toolOverrides?: {

package/dist/types/deviceSession.d.ts

@@ -353,13 +353,13 @@ export declare const deviceBackgroundCredentialResponseSchema: z.ZodObject<{
     accountId: z.ZodString;
     expiresAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    accountId: string;
     expiresAt: string;
+    accountId: string;
     deviceId: string;
     secret: string;
 }, {
-    accountId: string;
     expiresAt: string;
+    accountId: string;
     deviceId: string;
     secret: string;
 }>;
@@ -398,12 +398,12 @@ export declare const deviceBackgroundTokenResponseSchema: z.ZodObject<{
     expiresAt: z.ZodString;
     accountId: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    accountId: string;
     expiresAt: string;
+    accountId: string;
     accessToken: string;
 }, {
-    accountId: string;
     expiresAt: string;
+    accountId: string;
     accessToken: string;
 }>;
 export type DeviceBackgroundCredentialResponse = z.infer<typeof deviceBackgroundCredentialResponseSchema>;

package/dist/types/externalIdentity.d.ts

@@ -253,6 +253,7 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
+        email?: string | undefined;
         kind?: "bot" | "personal" | "organization" | "project" | "channel" | undefined;
         bio?: string | undefined;
         avatar?: string | null | undefined;
@@ -263,7 +264,6 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
         _id?: string | undefined;
-        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
@@ -307,6 +307,7 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
+        email?: string | undefined;
         kind?: "bot" | "personal" | "organization" | "project" | "channel" | undefined;
         bio?: string | undefined;
         avatar?: string | null | undefined;
@@ -317,7 +318,6 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
         _id?: string | undefined;
-        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
@@ -361,6 +361,7 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
+        email?: string | undefined;
         kind?: "bot" | "personal" | "organization" | "project" | "channel" | undefined;
         bio?: string | undefined;
         avatar?: string | null | undefined;
@@ -371,7 +372,6 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
         _id?: string | undefined;
-        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
@@ -415,6 +415,7 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
+        email?: string | undefined;
         kind?: "bot" | "personal" | "organization" | "project" | "channel" | undefined;
         bio?: string | undefined;
         avatar?: string | null | undefined;
@@ -425,7 +426,6 @@ export declare const resolveExternalIdentityResponseSchema: z.ZodEffects<z.ZodOb
         did?: string | undefined;
         verifiedDomains?: import("./identity").VerifiedDomain[] | undefined;
         _id?: string | undefined;
-        email?: string | undefined;
         phone?: string | undefined;
         address?: string | undefined;
         birthday?: string | undefined;
@@ -491,6 +491,7 @@ export declare const lookupExternalIdentitiesResponseSchema: z.ZodObject<{
         }>, "many">;
         redirectedUserIds: z.ZodArray<z.ZodString, "many">;
     }, "strip", z.ZodTypeAny, {
+        identifier: string;
         userId: string | null;
         externalIdentities: {
             canonicalAcct: string;
@@ -501,8 +502,8 @@ export declare const lookupExternalIdentitiesResponseSchema: z.ZodObject<{
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
-        identifier: string;
     }, {
+        identifier: string;
         userId: string | null;
         externalIdentities: {
             canonicalAcct: string;
@@ -513,10 +514,10 @@ export declare const lookupExternalIdentitiesResponseSchema: z.ZodObject<{
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
-        identifier: string;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     identities: {
+        identifier: string;
         userId: string | null;
         externalIdentities: {
             canonicalAcct: string;
@@ -527,10 +528,10 @@ export declare const lookupExternalIdentitiesResponseSchema: z.ZodObject<{
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
-        identifier: string;
     }[];
 }, {
     identities: {
+        identifier: string;
         userId: string | null;
         externalIdentities: {
             canonicalAcct: string;
@@ -541,7 +542,6 @@ export declare const lookupExternalIdentitiesResponseSchema: z.ZodObject<{
             sourceUserId: string;
         }[];
         redirectedUserIds: string[];
-        identifier: string;
     }[];
 }>;
 export type ExternalIdentityReference = z.infer<typeof externalIdentityReferenceSchema>;

package/dist/types/identityLink.d.ts

@@ -0,0 +1,210 @@
+/**
+ * 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';
+export declare const IDENTITY_LINK_STATUSES: readonly ["pending", "signed", "completed", "cancelled"];
+export type IdentityLinkStatus = (typeof IDENTITY_LINK_STATUSES)[number];
+/** The scheme and host Commons routes a link QR to. */
+export declare const IDENTITY_LINK_QR_PREFIX = "oxycommons://link";
+export declare const identityLinkIdSchema: z.ZodString;
+/** The QR auth.oxy.so shows: the request's id and the challenge Commons signs. */
+export declare function buildIdentityLinkQrPayload(linkId: string, challenge: string): string;
+/** The request a scanned code names, or `null` for anything that is not a link QR. */
+export declare function parseIdentityLinkQrPayload(raw: string): {
+    linkId: string;
+    challenge: string;
+} | null;
+/** `POST /identity/link` */
+export interface IdentityLinkCreateResponse {
+    linkId: string;
+    /** The one-use `link_identity` proof challenge, hex. */
+    challenge: string;
+    /** Unix milliseconds. */
+    expiresAt: number;
+    qrPayload: string;
+}
+export declare const identityLinkCreateResponseSchema: z.ZodType<IdentityLinkCreateResponse>;
+/** `GET /identity/link/:linkId` — what both devices poll. */
+export interface IdentityLinkState {
+    status: IdentityLinkStatus;
+    /** The account being linked: the proof's subject and actor. */
+    userId: string;
+    username: string | null;
+    /** The key Commons signed with, once it has. */
+    publicKey: string | null;
+    audience: string;
+    expiresAt: number;
+}
+export declare const identityLinkStateSchema: z.ZodType<IdentityLinkState>;
+/** `POST /identity/link/:linkId/proof` — from Commons, no bearer. */
+export declare const identityLinkProofRequestSchema: z.ZodObject<{
+    publicKey: z.ZodString;
+    proof: z.ZodObject<{
+        v: z.ZodLiteral<2>;
+        challenge: z.ZodString;
+        expiresAt: z.ZodNumber;
+        signature: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }, {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    publicKey: string;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+}, {
+    publicKey: string;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+}>;
+export type IdentityLinkProofRequest = z.infer<typeof identityLinkProofRequestSchema>;
+/** `POST /identity/link/:linkId/options` — WebAuthn request options over the challenge. */
+export declare const identityLinkOptionsRequestSchema: z.ZodObject<{
+    challenge: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    challenge: string;
+}, {
+    challenge: string;
+}>;
+export type IdentityLinkOptionsRequest = z.infer<typeof identityLinkOptionsRequestSchema>;
+/** `POST /identity/link/:linkId/complete` — the passkey assertion over the challenge. */
+export declare const identityLinkCompleteRequestSchema: z.ZodObject<{
+    assertion: z.ZodObject<{
+        id: z.ZodString;
+        rawId: z.ZodString;
+        type: z.ZodLiteral<"public-key">;
+        response: z.ZodObject<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">>;
+        clientExtensionResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        authenticatorAttachment: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        id: z.ZodString;
+        rawId: z.ZodString;
+        type: z.ZodLiteral<"public-key">;
+        response: z.ZodObject<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">>;
+        clientExtensionResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        authenticatorAttachment: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        id: z.ZodString;
+        rawId: z.ZodString;
+        type: z.ZodLiteral<"public-key">;
+        response: z.ZodObject<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            clientDataJSON: z.ZodString;
+            authenticatorData: z.ZodString;
+            signature: z.ZodString;
+            userHandle: z.ZodOptional<z.ZodString>;
+        }, z.ZodTypeAny, "passthrough">>;
+        clientExtensionResults: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        authenticatorAttachment: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>;
+}, "strict", z.ZodTypeAny, {
+    assertion: {
+        type: "public-key";
+        id: string;
+        rawId: string;
+        response: {
+            signature: string;
+            clientDataJSON: string;
+            authenticatorData: string;
+            userHandle?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        clientExtensionResults?: Record<string, unknown> | undefined;
+        authenticatorAttachment?: string | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+}, {
+    assertion: {
+        type: "public-key";
+        id: string;
+        rawId: string;
+        response: {
+            signature: string;
+            clientDataJSON: string;
+            authenticatorData: string;
+            userHandle?: string | undefined;
+        } & {
+            [k: string]: unknown;
+        };
+        clientExtensionResults?: Record<string, unknown> | undefined;
+        authenticatorAttachment?: string | undefined;
+    } & {
+        [k: string]: unknown;
+    };
+}>;
+export type IdentityLinkCompleteRequest = z.infer<typeof identityLinkCompleteRequestSchema>;

package/dist/types/identityProof.d.ts

@@ -27,26 +27,12 @@ export declare const IDENTITY_PROOF_CHALLENGE_TTL_MS: number;
  * action and spent only by a proof for that action.
  */
 export declare const IDENTITY_PROOF_ACTIONS: {
-    /** A keyless account's FIRST root, stored with its web envelope. */
-    readonly establish: "web_envelope_establish";
-    /** Replace the web envelope (add or remove a wrap, re-seal). */
-    readonly put: "web_envelope_put";
-    /** Record that the recovery material is written down. */
-    readonly phraseConfirmed: "web_envelope_phrase_confirmed";
-    /** Record that the recovery material re-derived the root. */
-    readonly recoveryVerified: "web_envelope_recovery_verified";
-    /** Remove the web holder. */
-    readonly 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).
+     */
     readonly link: "link_identity";
-    /** Create a personal account together with its root (passkey sign-up). */
-    readonly enroll: "enroll_identity";
-    /** Prove the root to start signed-out recovery. */
-    readonly recoverStart: "recover_account_start";
-    /** Bind the new passkey and envelope when completing signed-out recovery. */
-    readonly recoverComplete: "recover_account_complete";
-    /** Seal the root for the Commons device that joined a move (payload: move id + sealed bytes). */
-    readonly moveSeal: "identity_move_seal";
 };
 export type IdentityProofAction = (typeof IDENTITY_PROOF_ACTIONS)[keyof typeof IDENTITY_PROOF_ACTIONS];
 export declare const IDENTITY_PROOF_ACTION_VALUES: [IdentityProofAction, ...IdentityProofAction[]];
@@ -64,7 +50,7 @@ export interface IdentityProofClaims {
     rootPublicKey: string;
     /** SHA-256 hex of `canonicalJson(payload)`, or `null` when the operation has no payload. */
     payloadDigest: string | null;
-    /** The envelope revision the operation expects to replace, or `null`. */
+    /** The revision the operation expects to replace, or `null` when it replaces nothing. */
     expectedRevision: number | null;
     audience: string;
     /** The one-use server challenge. */
@@ -103,11 +89,11 @@ export declare const identityProofSchema: z.ZodObject<{
 export type IdentityProof = z.infer<typeof identityProofSchema>;
 /** `POST /identity/proof-challenge` */
 export declare const identityProofChallengeRequestSchema: z.ZodObject<{
-    action: z.ZodEnum<[IdentityProofAction, ...IdentityProofAction[]]>;
+    action: z.ZodEnum<["link_identity", ..."link_identity"[]]>;
 }, "strip", z.ZodTypeAny, {
-    action: IdentityProofAction;
+    action: "link_identity";
 }, {
-    action: IdentityProofAction;
+    action: "link_identity";
 }>;
 export type IdentityProofChallengeRequest = z.infer<typeof identityProofChallengeRequestSchema>;
 export interface IdentityProofChallengeResponse {
@@ -123,34 +109,21 @@ export declare const identityProofChallengeResponseSchema: z.ZodType<IdentityPro
  */
 export declare const IDENTITY_ERROR_CODES: {
     readonly proofInvalid: "IDENTITY_PROOF_INVALID";
-    readonly revisionConflict: "IDENTITY_ENVELOPE_REVISION_CONFLICT";
     readonly rootAlreadyLinked: "IDENTITY_ROOT_ALREADY_LINKED";
     readonly rootLinkedElsewhere: "IDENTITY_ROOT_LINKED_ELSEWHERE";
-    readonly noRoot: "IDENTITY_NO_ROOT";
     readonly freshFactorRequired: "IDENTITY_FRESH_FACTOR_REQUIRED";
-    readonly lastWebHolder: "IDENTITY_LAST_WEB_HOLDER";
-    readonly enrollmentRequired: "IDENTITY_ENROLLMENT_REQUIRED";
-    readonly enrollmentInvalid: "IDENTITY_ENROLLMENT_INVALID";
     readonly notPersonal: "IDENTITY_NOT_PERSONAL_ACCOUNT";
-    readonly recoveryFailed: "IDENTITY_RECOVERY_FAILED";
 };
 export type IdentityErrorCode = (typeof IDENTITY_ERROR_CODES)[keyof typeof IDENTITY_ERROR_CODES];
 /**
- * `GET /identity/root-status` — non-sensitive readiness metadata any first-party
- * surface (Accounts, the account menu) may read with a bearer to show a reminder,
- * without the ciphertext and without opening anything (ADR 0024 D5).
+ * `GET /identity/root-status` — how the signed-in account is kept (ADR 0029 D3),
+ * for Accounts and the account menu to recommend linking Commons. Read with a
+ * bearer from any first-party origin.
  */
 export interface IdentityRootStatus {
-    /** Whether the account has a root at all. */
+    /** Whether Commons' root is linked: the account is self-custodied. */
     rootLinked: boolean;
-    /** Passkeys whose wraps can open the web holder, and how many have proven it. `null`: no web holder. */
-    webHolder: {
-        passkeys: number;
-        verifiedPasskeys: number;
-    } | null;
-    /** Whether the root has recovery words (a raw-key root does not). `null` when unknown (no web holder). */
-    hasPhrase: boolean | null;
-    phraseConfirmedAt: string | null;
-    recoveryVerifiedAt: string | null;
+    /** The recovery email of a passkey account; `null` once Commons is linked. */
+    recoveryEmail: string | null;
 }
 export declare const identityRootStatusSchema: z.ZodType<IdentityRootStatus>;

package/dist/types/index.d.ts

@@ -49,18 +49,16 @@ export { rotateKeyChallengeResponseSchema, rotateKeyCompleteRequestSchema, rotat
 export type { RotateKeyChallengeResponse, RotateKeyCompleteRequest, RotateKeyCompleteResponse, } from './keyRotation';
 export { backupLookupIdSchema, encryptedBackupEnvelopeSchema, backupUploadRequestSchema, backupStatusResponseSchema, } from './keyRecovery';
 export type { EncryptedBackupEnvelope, BackupUploadRequest, BackupStatusResponse, } from './keyRecovery';
-export { WEB_IDENTITY_ENVELOPE_VERSION, WEB_IDENTITY_SECRET_KINDS, webIdentityPublicKeySchema, webauthnCredentialIdSchema, webauthnRpIdSchema, webIdentityWrapSchema, webIdentityEnvelopeSchema, webIdentityEnvelopeUploadSchema, webIdentityHolderSchema, webIdentityEnvelopeResponseSchema, webIdentityEnvelopeProofFieldsSchema, webIdentityEnvelopeActionSchema, webIdentityEnvelopePutSchema, webauthnAssertionResponseSchema, webIdentityEnvelopeEstablishSchema, } from './webIdentityCarrier';
 export { 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';
-export { IDENTITY_RECOVERY_TTL_MS, identityRecoveryChallengeResponseSchema, identityRecoveryStartRequestSchema, identityRecoveryCompleteRequestSchema, } from './identityRecovery';
-export type { IdentityRecoveryChallengeResponse, IdentityRecoveryStartRequest, IdentityRecoveryStartResponse, IdentityRecoveryCompleteRequest, } from './identityRecovery';
 export type { IdentityProofAction, IdentityErrorCode, IdentityProofClaims, IdentityProof, IdentityProofChallengeRequest, IdentityProofChallengeResponse, IdentityRootStatus, } from './identityProof';
-export { 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';
-export type { IdentityMoveStatus, IdentityMoveCreateRequest, IdentityMoveCreateResponse, IdentityMoveJoinRequest, IdentityMoveSealRequest, IdentityMoveReceiptRequest, IdentityMoveRevealRequest, IdentityMoveState, } from './identityMove';
-export type { WebIdentityWrap, WebIdentityEnvelope, WebIdentitySecretKind, WebIdentityHolder, WebIdentityEnvelopeAction, WebauthnAssertionResponse, WebIdentityEnvelopeUpload, WebIdentityEnvelopeResponse, WebIdentityEnvelopePut, WebIdentityEnvelopeEstablish, } from './webIdentityCarrier';
 export { updatePlatformSchema, updateStatusSchema, updateAssetStatusSchema, sha256HexSchema, channelNameSchema, runtimeVersionSchema, rolloutPercentSchema, assetInitItemSchema, assetInitRequestSchema, assetUploadTicketSchema, assetInitResponseSchema, assetCompleteRequestSchema, assetCompleteResultItemSchema, assetCompleteResponseSchema, updateAssetRefSchema, createUpdateRequestSchema, updateSchema, createUpdateResponseSchema, rollbackToEmbeddedEntrySchema, channelSchema, channelListResponseSchema, updateListResponseSchema, rollbackRequestSchema, rollbackToEmbeddedRequestSchema, promoteRequestSchema, updateRolloutPatchSchema, } from './updates';
 export type { UpdatePlatform, UpdateStatus, UpdateAssetStatus, AssetInitItem, AssetInitRequest, AssetUploadTicket, AssetInitResponse, AssetCompleteRequest, AssetCompleteResultItem, AssetCompleteResponse, UpdateAssetRef, CreateUpdateRequest, Update, CreateUpdateResponse, RollbackToEmbeddedEntry, Channel, ChannelListResponse, UpdateListResponse, RollbackRequest, RollbackToEmbeddedRequest, PromoteRequest, UpdateRolloutPatch, } from './updates';
-export { webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, } from './webauthn';
-export type { WebauthnRegisterOptionsRequest, WebauthnLoginOptionsRequest, WebauthnRegisterVerifyRequest, WebauthnLoginVerifyRequest, } from './webauthn';
+export { webauthnRegisterOptionsRequestSchema, webauthnLoginOptionsRequestSchema, webauthnRegisterVerifyRequestSchema, webauthnLoginVerifyRequestSchema, webauthnCredentialIdSchema, webauthnAssertionResponseSchema, } from './webauthn';
+export type { WebauthnRegisterOptionsRequest, WebauthnLoginOptionsRequest, WebauthnRegisterVerifyRequest, WebauthnLoginVerifyRequest, WebauthnAssertionResponse, } from './webauthn';
+export { 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';
+export { IDENTITY_LINK_STATUSES, IDENTITY_LINK_QR_PREFIX, identityLinkIdSchema, buildIdentityLinkQrPayload, parseIdentityLinkQrPayload, identityLinkCreateResponseSchema, identityLinkStateSchema, identityLinkProofRequestSchema, identityLinkOptionsRequestSchema, identityLinkCompleteRequestSchema, } from './identityLink';
+export type { IdentityLinkStatus, IdentityLinkCreateResponse, IdentityLinkState, IdentityLinkProofRequest, IdentityLinkOptionsRequest, IdentityLinkCompleteRequest, } from './identityLink';
+export type { EmailVerificationPurpose, EmailVerificationStartRequest, EmailVerificationStartResponse, EmailVerificationConfirmRequest, EmailVerificationConfirmResponse, EmailVerificationErrorCode, } from './accountEmail';
 export { transparencyCheckpointSignatureSchema, transparencyAnchorSchema, transparencyCheckpointSchema, transparencyInclusionProofSchema, transparencyCheckpointListSchema, } from './transparency';
 export type { TransparencyCheckpointSignature, TransparencyAnchor, TransparencyCheckpoint, TransparencyInclusionProof, TransparencyCheckpointList, } from './transparency';
 export { INFERENCE_CONTRACT_VERSION, } from './inference/version';