@oxy.so/contracts 2.1.0 → 3.0.0

package/dist/types/accountEmail.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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`).
+ */
+import { z } from '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.
+ */
+export declare const EMAIL_VERIFICATION_PURPOSES: readonly ["signup", "signin", "reauth"];
+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.ZodObject<{
+    purpose: z.ZodLiteral<"signup">;
+    email: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    purpose: "signup";
+    email: string;
+}, {
+    purpose: "signup";
+    email: 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;
+}
+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 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/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/deviceBoot.d.ts

@@ -4,8 +4,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/types/deviceSession.d.ts

@@ -166,9 +166,10 @@ export type DeviceSessionSync = z.infer<typeof deviceSessionSyncSchema>;
 /**
  * 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),
@@ -196,8 +197,8 @@ export declare const deviceTokenMintRequestSchema: z.ZodObject<{
  * 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.
  */
 export declare const deviceTokenMintResponseSchema: z.ZodObject<{
     accessToken: z.ZodString;
@@ -330,12 +331,11 @@ export type SessionAccountsChangedEvent = z.infer<typeof sessionAccountsChangedE
  * 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
@@ -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;
 }>;
@@ -368,10 +368,10 @@ export declare const deviceBackgroundCredentialResponseSchema: z.ZodObject<{
  * 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.
  */
 export declare const deviceBackgroundTokenRequestSchema: z.ZodObject<{
     deviceId: z.ZodString;
@@ -398,14 +398,126 @@ 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>;
 export type DeviceBackgroundTokenRequest = z.infer<typeof deviceBackgroundTokenRequestSchema>;
 export type DeviceBackgroundTokenResponse = z.infer<typeof deviceBackgroundTokenResponseSchema>;
+/**
+ * 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.
+ */
+export declare const deviceProofSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+/**
+ * `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.
+ */
+export declare const deviceRegisterResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+/**
+ * `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.
+ */
+export declare const deviceJoinCodeRequestSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+} & {
+    clientId: z.ZodString;
+    redirectUri: z.ZodString;
+    codeChallenge: z.ZodString;
+    codeChallengeMethod: z.ZodLiteral<"S256">;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}, {
+    deviceId: string;
+    deviceSecret: string;
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}>;
+export declare const deviceJoinCodeResponseSchema: z.ZodObject<{
+    code: z.ZodString;
+    /** Seconds until the code expires. */
+    expiresIn: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    expiresIn: number;
+}, {
+    code: string;
+    expiresIn: number;
+}>;
+/**
+ * `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`.
+ */
+export declare const deviceJoinRequestSchema: z.ZodObject<{
+    code: z.ZodString;
+    codeVerifier: z.ZodString;
+    clientId: z.ZodString;
+    redirectUri: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+}, {
+    code: string;
+    clientId: string;
+    redirectUri: string;
+    codeVerifier: string;
+}>;
+export declare const deviceJoinResponseSchema: z.ZodObject<{
+    deviceId: z.ZodString;
+    deviceSecret: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    deviceId: string;
+    deviceSecret: string;
+}, {
+    deviceId: string;
+    deviceSecret: string;
+}>;
+export type DeviceProof = z.infer<typeof deviceProofSchema>;
+export type DeviceRegisterResponse = z.infer<typeof deviceRegisterResponseSchema>;
+export type DeviceJoinCodeRequest = z.infer<typeof deviceJoinCodeRequestSchema>;
+export type DeviceJoinCodeResponse = z.infer<typeof deviceJoinCodeResponseSchema>;
+export type DeviceJoinRequest = z.infer<typeof deviceJoinRequestSchema>;
+export type DeviceJoinResponse = z.infer<typeof deviceJoinResponseSchema>;

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;

package/dist/types/identity.d.ts

@@ -315,18 +315,14 @@ export type DomainVerificationInstructions = z.infer<typeof domainVerificationIn
 /**
  * One linked authentication method. Mirrors a `User.authMethods[]` entry.
  * `verificationMethodId` is present for `identity` methods (a key), linking the
- * auth method to its DID verification-method fragment. For `webauthn` methods
- * `credentialId` identifies the specific passkey (one entry per registered
- * credential) and `name` is its user-facing label; a passkey is NOT a DID
- * verification method, so it carries no `verificationMethodId` (a passkey-only
- * account stays custodial).
+ * auth method to its DID verification-method fragment. A key is the only
+ * linked method: an email, a password and an authenticator are sign-in
+ * factors of the account, not DID verification methods.
  */
 export interface AuthMethodEntry {
-    type: 'identity' | 'webauthn';
+    type: 'identity';
     linkedAt: string | Date;
     verificationMethodId?: string;
-    credentialId?: string;
-    name?: string;
 }
 export declare const authMethodEntrySchema: z.ZodType<AuthMethodEntry>;
 /**

package/dist/types/identityLink.d.ts

@@ -0,0 +1,146 @@
+/**
+ * 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.
+ */
+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/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).
+ */
+export declare const identityLinkCompleteRequestSchema: z.ZodObject<{
+    reauth: z.ZodObject<{
+        emailCode: z.ZodObject<{
+            verificationId: z.ZodString;
+            code: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            code: string;
+            verificationId: string;
+        }, {
+            code: string;
+            verificationId: string;
+        }>;
+        totpCode: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        emailCode: {
+            code: string;
+            verificationId: string;
+        };
+        totpCode?: string | undefined;
+    }, {
+        emailCode: {
+            code: string;
+            verificationId: string;
+        };
+        totpCode?: string | undefined;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    reauth: {
+        emailCode: {
+            code: string;
+            verificationId: string;
+        };
+        totpCode?: string | undefined;
+    };
+}, {
+    reauth: {
+        emailCode: {
+            code: string;
+            verificationId: string;
+        };
+        totpCode?: string | undefined;
+    };
+}>;
+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 an account that has none (`POST /auth/link`).
+     * The account becomes self-custodied and its 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 email of an account without a key; `null` once Commons is linked. */
+    recoveryEmail: string | null;
 }
 export declare const identityRootStatusSchema: z.ZodType<IdentityRootStatus>;