@oxy.so/contracts 1.2.0 → 1.3.0

package/dist/types/webIdentityCarrier.d.ts

@@ -1,30 +1,32 @@
 /**
- * Web identity carrier contract — "one identity, two carriers".
+ * Web identity holder contract — the sealed envelope that lets a browser hold an
+ * account's self-custody root without Oxy ever being able to use it (ADR 0024).
  *
- * SINGLE SOURCE OF TRUTH for the sealed envelope that lets a browser carry an
- * account's self-custody identity without Oxy ever holding it
- * (`docs/superpowers/specs/2026-09-15-one-identity-two-carriers-design.md`).
+ * A root is a BIP-39 phrase (12–24 words) whose seed's first 32 bytes are the
+ * secp256k1 key — exactly the Commons derivation — or, for a few imported
+ * identities, a raw private key that never had a phrase. On the web it travels as:
  *
- * The identity is a BIP-39 mnemonic whose seed's first 32 bytes are the
- * secp256k1 key — exactly the Commons derivation — so a web identity and a
- * Commons identity are the same thing. On the web it travels as:
- *
- *   entropy (16 bytes) ── XChaCha20-Poly1305 under a random DEK ──▶ sealedEntropy
- *   DEK ── XChaCha20-Poly1305 under KEK_i ──▶ wraps[i]
+ *   secret ── XChaCha20-Poly1305 under a random DEK ──▶ sealedSecret
+ *   DEK    ── XChaCha20-Poly1305 under KEK_i ──▶ wraps[i]
  *   KEK_i = HKDF(PRF output of passkey i)
  *
  * The server stores the envelope and can open NONE of it: the PRF output never
- * leaves the user's authenticator, and the mnemonic is never uploaded. The AEAD
- * associated data binds every ciphertext to the identity's public key (and each
- * wrap to its credential), so a re-labelled or transplanted envelope fails to
- * open instead of decrypting into the wrong identity.
+ * leaves the user's authenticator, and the secret is never uploaded. The AEAD
+ * associated data binds the secret to the root's public key and kind, and each
+ * wrap to its credential and RP ID, so a re-labelled or transplanted envelope
+ * fails to open instead of decrypting into the wrong identity.
  *
- * Every hex field is lowercase-or-uppercase hex. Platform-agnostic — zod only,
- * ESM-safe (no `require()`).
+ * Platform-agnostic — zod only, ESM-safe (no `require()`).
  */
 import { z } from 'zod';
-/** The only envelope version. A scheme change is a new literal, never a mutation. */
-export declare const WEB_IDENTITY_ENVELOPE_VERSION: 1;
+/** The envelope scheme. A scheme change is a new literal, never a mutation. */
+export declare const WEB_IDENTITY_ENVELOPE_VERSION: 2;
+/**
+ * What an envelope seals. A raw-key identity stays a raw-key identity:
+ * nothing ever derives or displays a phrase for it.
+ */
+export declare const WEB_IDENTITY_SECRET_KINDS: readonly ["mnemonic-entropy", "raw-private-key"];
+export type WebIdentitySecretKind = (typeof WEB_IDENTITY_SECRET_KINDS)[number];
 /**
  * The identity's secp256k1 public key in Oxy's canonical form: uncompressed SEC1
  * (`04` + 64 bytes), lowercase hex — what `KeyManager.derivePublicKey` produces
@@ -33,6 +35,8 @@ export declare const WEB_IDENTITY_ENVELOPE_VERSION: 1;
 export declare const webIdentityPublicKeySchema: z.ZodString;
 /** A WebAuthn credential id, base64url as the browser reports it. */
 export declare const webauthnCredentialIdSchema: z.ZodString;
+/** A WebAuthn RP ID: a bare registrable host name, lowercase. */
+export declare const webauthnRpIdSchema: z.ZodString;
 /** One passkey's wrap of the envelope's data key. */
 export declare const webIdentityWrapSchema: z.ZodObject<{
     credentialId: z.ZodString;
@@ -41,16 +45,27 @@ export declare const webIdentityWrapSchema: z.ZodObject<{
     /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
     wrappedKey: z.ZodString;
     createdAt: z.ZodString;
+    /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+    rpId: z.ZodString;
+    /**
+     * When this passkey's PRF output was shown to open the envelope. A wrap is a
+     * root HOLDER only once this is set; a login passkey never is by default.
+     */
+    verifiedAt: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     credentialId: string;
     createdAt: string;
     nonce: string;
     wrappedKey: string;
+    rpId: string;
+    verifiedAt?: string | undefined;
 }, {
     credentialId: string;
     createdAt: string;
     nonce: string;
     wrappedKey: string;
+    rpId: string;
+    verifiedAt?: string | undefined;
 }>;
 /**
  * The sealed identity as it is stored (server copy and local copy alike).
@@ -58,14 +73,18 @@ export declare const webIdentityWrapSchema: z.ZodObject<{
  * `wraps` holds one entry per passkey able to open it; at least one, and a
  * bounded number so an envelope cannot grow without limit.
  */
-export declare const webIdentityEnvelopeSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
+export declare const webIdentityEnvelopeSchema: z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<2>;
     algorithm: z.ZodLiteral<"xchacha20poly1305">;
     publicKey: z.ZodString;
-    /** 24-byte nonce of the entropy seal. */
-    entropyNonce: z.ZodString;
-    /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-    sealedEntropy: z.ZodString;
+    secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+    /** 24-byte nonce of the secret seal. */
+    secretNonce: z.ZodString;
+    /**
+     * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+     * (12–24 words) or a 32-byte private key, plus 16.
+     */
+    sealedSecret: z.ZodString;
     wraps: z.ZodArray<z.ZodObject<{
         credentialId: z.ZodString;
         /** 24-byte XChaCha20-Poly1305 nonce. */
@@ -73,40 +92,87 @@ export declare const webIdentityEnvelopeSchema: z.ZodObject<{
         /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
         wrappedKey: z.ZodString;
         createdAt: z.ZodString;
+        /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+        rpId: z.ZodString;
+        /**
+         * When this passkey's PRF output was shown to open the envelope. A wrap is a
+         * root HOLDER only once this is set; a login passkey never is by default.
+         */
+        verifiedAt: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         credentialId: string;
         createdAt: string;
         nonce: string;
         wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
     }, {
         credentialId: string;
         createdAt: string;
         nonce: string;
         wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
-    version: 1;
+    version: 2;
     publicKey: string;
     algorithm: "xchacha20poly1305";
-    entropyNonce: string;
-    sealedEntropy: string;
+    secretKind: "mnemonic-entropy" | "raw-private-key";
+    secretNonce: string;
+    sealedSecret: string;
     wraps: {
         credentialId: string;
         createdAt: string;
         nonce: string;
         wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
     }[];
 }, {
-    version: 1;
+    version: 2;
     publicKey: string;
     algorithm: "xchacha20poly1305";
-    entropyNonce: string;
-    sealedEntropy: string;
+    secretKind: "mnemonic-entropy" | "raw-private-key";
+    secretNonce: string;
+    sealedSecret: string;
     wraps: {
         credentialId: string;
         createdAt: string;
         nonce: string;
         wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
+    }[];
+}>, {
+    version: 2;
+    publicKey: string;
+    algorithm: "xchacha20poly1305";
+    secretKind: "mnemonic-entropy" | "raw-private-key";
+    secretNonce: string;
+    sealedSecret: string;
+    wraps: {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
+    }[];
+}, {
+    version: 2;
+    publicKey: string;
+    algorithm: "xchacha20poly1305";
+    secretKind: "mnemonic-entropy" | "raw-private-key";
+    secretNonce: string;
+    sealedSecret: string;
+    wraps: {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+        rpId: string;
+        verifiedAt?: string | undefined;
     }[];
 }>;
 /**
@@ -116,14 +182,18 @@ export declare const webIdentityEnvelopeSchema: z.ZodObject<{
  * account: an envelope can only ever carry the account's own identity.
  */
 export declare const webIdentityEnvelopeUploadSchema: z.ZodObject<{
-    envelope: z.ZodObject<{
-        version: z.ZodLiteral<1>;
+    envelope: z.ZodEffects<z.ZodObject<{
+        version: z.ZodLiteral<2>;
         algorithm: z.ZodLiteral<"xchacha20poly1305">;
         publicKey: z.ZodString;
-        /** 24-byte nonce of the entropy seal. */
-        entropyNonce: z.ZodString;
-        /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-        sealedEntropy: z.ZodString;
+        secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+        /** 24-byte nonce of the secret seal. */
+        secretNonce: z.ZodString;
+        /**
+         * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+         * (12–24 words) or a 32-byte private key, plus 16.
+         */
+        sealedSecret: z.ZodString;
         wraps: z.ZodArray<z.ZodObject<{
             credentialId: z.ZodString;
             /** 24-byte XChaCha20-Poly1305 nonce. */
@@ -131,81 +201,159 @@ export declare const webIdentityEnvelopeUploadSchema: z.ZodObject<{
             /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
             wrappedKey: z.ZodString;
             createdAt: z.ZodString;
+            /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+            rpId: z.ZodString;
+            /**
+             * When this passkey's PRF output was shown to open the envelope. A wrap is a
+             * root HOLDER only once this is set; a login passkey never is by default.
+             */
+            verifiedAt: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        version: 1;
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>, {
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }>;
 }, "strip", z.ZodTypeAny, {
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
 }, {
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
 }>;
-/** `GET /identity/web-envelope` — the caller's envelope and its recovery-phrase state. */
+/** A root holder as the status read reports it — metadata only, nothing that opens anything. */
+export declare const webIdentityHolderSchema: z.ZodObject<{
+    credentialId: z.ZodString;
+    rpId: z.ZodString;
+    verifiedAt: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    credentialId: string;
+    createdAt: string;
+    verifiedAt: string | null;
+    rpId: string;
+}, {
+    credentialId: string;
+    createdAt: string;
+    verifiedAt: string | null;
+    rpId: string;
+}>;
+/**
+ * `GET /identity/web-envelope` — the caller's envelope and the readiness facts
+ * ADR 0024 D5 keeps separate. A client decides what to show from these fields
+ * WITHOUT decrypting anything.
+ */
 export declare const webIdentityEnvelopeResponseSchema: z.ZodObject<{
-    envelope: z.ZodNullable<z.ZodObject<{
-        version: z.ZodLiteral<1>;
+    envelope: z.ZodNullable<z.ZodEffects<z.ZodObject<{
+        version: z.ZodLiteral<2>;
         algorithm: z.ZodLiteral<"xchacha20poly1305">;
         publicKey: z.ZodString;
-        /** 24-byte nonce of the entropy seal. */
-        entropyNonce: z.ZodString;
-        /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-        sealedEntropy: z.ZodString;
+        secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+        /** 24-byte nonce of the secret seal. */
+        secretNonce: z.ZodString;
+        /**
+         * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+         * (12–24 words) or a 32-byte private key, plus 16.
+         */
+        sealedSecret: z.ZodString;
         wraps: z.ZodArray<z.ZodObject<{
             credentialId: z.ZodString;
             /** 24-byte XChaCha20-Poly1305 nonce. */
@@ -213,111 +361,261 @@ export declare const webIdentityEnvelopeResponseSchema: z.ZodObject<{
             /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
             wrappedKey: z.ZodString;
             createdAt: z.ZodString;
+            /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+            rpId: z.ZodString;
+            /**
+             * When this passkey's PRF output was shown to open the envelope. A wrap is a
+             * root HOLDER only once this is set; a login passkey never is by default.
+             */
+            verifiedAt: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }>>;
-    /**
-     * When the owner confirmed they wrote the recovery phrase down, or `null`.
-     * Until then the identity must not be unlocked on a second device, nor used
-     * for any operation that needs the key (design decision D2).
-     */
+    /** The revision a write must name as `expectedRevision`; `0` when there is no envelope. */
+    revision: z.ZodNumber;
+    /** Whether the account has a linked root at all (it may live only in Commons). */
+    rootLinked: z.ZodBoolean;
+    /** The web wraps, as metadata. */
+    holders: z.ZodArray<z.ZodObject<{
+        credentialId: z.ZodString;
+        rpId: z.ZodString;
+        verifiedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        credentialId: string;
+        createdAt: string;
+        verifiedAt: string | null;
+        rpId: string;
+    }, {
+        credentialId: string;
+        createdAt: string;
+        verifiedAt: string | null;
+        rpId: string;
+    }>, "many">;
+    /** When the owner confirmed the recovery material is written down, or `null`. */
     phraseConfirmedAt: z.ZodNullable<z.ZodString>;
+    /** When the recovery material was shown to re-derive this root, or `null`. */
+    recoveryVerifiedAt: z.ZodNullable<z.ZodString>;
     updatedAt: z.ZodNullable<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     updatedAt: string | null;
+    revision: number;
+    rootLinked: boolean;
+    phraseConfirmedAt: string | null;
+    recoveryVerifiedAt: string | null;
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     } | null;
-    phraseConfirmedAt: string | null;
+    holders: {
+        credentialId: string;
+        createdAt: string;
+        verifiedAt: string | null;
+        rpId: string;
+    }[];
 }, {
     updatedAt: string | null;
+    revision: number;
+    rootLinked: boolean;
+    phraseConfirmedAt: string | null;
+    recoveryVerifiedAt: string | null;
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     } | null;
-    phraseConfirmedAt: string | null;
+    holders: {
+        credentialId: string;
+        createdAt: string;
+        verifiedAt: string | null;
+        rpId: string;
+    }[];
+}>;
+/** A root proof, plus the envelope revision the write expects to replace. */
+export declare const webIdentityEnvelopeProofFieldsSchema: z.ZodObject<{
+    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;
+    }>;
+    expectedRevision: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    expectedRevision: number;
+}, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    expectedRevision: number;
 }>;
 /**
- * `POST /identity/web-envelope/phrase-confirmed` and
- * `DELETE /identity/web-envelope` both prove control of the identity key, not
- * just a bearer: a stolen session must not be able to mark a phrase as saved or
- * destroy the web copy of someone's identity.
- *
- * The signed message is `JSON.stringify({ action, userId, timestamp })` — the
- * same scheme as `link_identity`.
+ * `POST /identity/web-envelope/phrase-confirmed`, `/recovery-verified` and
+ * `DELETE /identity/web-envelope` prove control of the root, not just a bearer.
  */
-export declare const webIdentityEnvelopeProofSchema: z.ZodObject<{
-    signature: z.ZodString;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    signature: string;
-    timestamp: number;
+export declare const webIdentityEnvelopeActionSchema: z.ZodObject<{
+    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;
+    }>;
+    expectedRevision: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    expectedRevision: number;
 }, {
-    signature: string;
-    timestamp: number;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
+    expectedRevision: number;
 }>;
-/** `PUT /identity/web-envelope` body: the envelope plus a `web_envelope_put` identity-key proof. */
+/** `PUT /identity/web-envelope` body. */
 export declare const webIdentityEnvelopePutSchema: z.ZodObject<{
-    envelope: z.ZodObject<{
-        version: z.ZodLiteral<1>;
+    envelope: z.ZodEffects<z.ZodObject<{
+        version: z.ZodLiteral<2>;
         algorithm: z.ZodLiteral<"xchacha20poly1305">;
         publicKey: z.ZodString;
-        /** 24-byte nonce of the entropy seal. */
-        entropyNonce: z.ZodString;
-        /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-        sealedEntropy: z.ZodString;
+        secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+        /** 24-byte nonce of the secret seal. */
+        secretNonce: z.ZodString;
+        /**
+         * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+         * (12–24 words) or a 32-byte private key, plus 16.
+         */
+        sealedSecret: z.ZodString;
         wraps: z.ZodArray<z.ZodObject<{
             credentialId: z.ZodString;
             /** 24-byte XChaCha20-Poly1305 nonce. */
@@ -325,96 +623,247 @@ export declare const webIdentityEnvelopePutSchema: z.ZodObject<{
             /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
             wrappedKey: z.ZodString;
             createdAt: z.ZodString;
+            /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+            rpId: z.ZodString;
+            /**
+             * When this passkey's PRF output was shown to open the envelope. A wrap is a
+             * root HOLDER only once this is set; a login passkey never is by default.
+             */
+            verifiedAt: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        version: 1;
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }>;
 } & {
-    signature: z.ZodString;
-    timestamp: z.ZodNumber;
-}, "strip", z.ZodTypeAny, {
-    signature: string;
-    timestamp: number;
+    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;
+    }>;
+    expectedRevision: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
+    expectedRevision: number;
 }, {
-    signature: string;
-    timestamp: number;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
+    expectedRevision: number;
 }>;
 /**
- * `POST /identity/web-envelope/establish` body — create an account's FIRST
- * identity on the web: link the key and store its envelope in ONE transaction.
- *
- * Linking and storing as two calls would let a failure (or a closed tab) in
- * between leave the account bound to a key that nothing carries — an identity
- * lost at birth. `link` is a `link_identity` proof and the outer proof a
- * `web_envelope_put` proof, both signed by the envelope's own key.
+ * A WebAuthn assertion by one of the account's EXISTING passkeys whose
+ * `clientDataJSON.challenge` is the proof challenge — the fresh use of the
+ * existing factor a keyless account needs before its first root is linked.
+ */
+export declare const webauthnAssertionResponseSchema: 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">>;
+/**
+ * `POST /identity/web-envelope/establish` body — an account's FIRST root, linked
+ * and stored with its envelope in ONE transaction: one root proof
+ * (`web_envelope_establish`, digest of the envelope) plus a fresh `assertion` by
+ * an existing passkey over the same challenge.
  */
 export declare const webIdentityEnvelopeEstablishSchema: z.ZodObject<{
-    envelope: z.ZodObject<{
-        version: z.ZodLiteral<1>;
+    envelope: z.ZodEffects<z.ZodObject<{
+        version: z.ZodLiteral<2>;
         algorithm: z.ZodLiteral<"xchacha20poly1305">;
         publicKey: z.ZodString;
-        /** 24-byte nonce of the entropy seal. */
-        entropyNonce: z.ZodString;
-        /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-        sealedEntropy: z.ZodString;
+        secretKind: z.ZodEnum<["mnemonic-entropy", "raw-private-key"]>;
+        /** 24-byte nonce of the secret seal. */
+        secretNonce: z.ZodString;
+        /**
+         * The sealed secret, tag appended: 16/20/24/28/32 bytes of BIP-39 entropy
+         * (12–24 words) or a 32-byte private key, plus 16.
+         */
+        sealedSecret: z.ZodString;
         wraps: z.ZodArray<z.ZodObject<{
             credentialId: z.ZodString;
             /** 24-byte XChaCha20-Poly1305 nonce. */
@@ -422,101 +871,260 @@ export declare const webIdentityEnvelopeEstablishSchema: z.ZodObject<{
             /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
             wrappedKey: z.ZodString;
             createdAt: z.ZodString;
+            /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+            rpId: z.ZodString;
+            /**
+             * When this passkey's PRF output was shown to open the envelope. A wrap is a
+             * root HOLDER only once this is set; a login passkey never is by default.
+             */
+            verifiedAt: z.ZodOptional<z.ZodString>;
         }, "strip", z.ZodTypeAny, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }, {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }, {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }>, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
+        }[];
+    }, {
+        version: 2;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     }>;
 } & {
-    signature: z.ZodString;
-    timestamp: z.ZodNumber;
-} & {
-    link: z.ZodObject<{
+    proof: z.ZodObject<{
+        v: z.ZodLiteral<2>;
+        challenge: z.ZodString;
+        expiresAt: z.ZodNumber;
         signature: z.ZodString;
-        timestamp: z.ZodNumber;
     }, "strip", z.ZodTypeAny, {
+        expiresAt: number;
         signature: string;
-        timestamp: number;
+        v: 2;
+        challenge: string;
     }, {
+        expiresAt: number;
         signature: string;
-        timestamp: number;
+        v: 2;
+        challenge: string;
     }>;
-}, "strip", z.ZodTypeAny, {
-    signature: string;
-    timestamp: number;
+    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, {
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
-    link: {
-        signature: string;
-        timestamp: number;
+    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;
     };
 }, {
-    signature: string;
-    timestamp: number;
+    proof: {
+        expiresAt: number;
+        signature: string;
+        v: 2;
+        challenge: string;
+    };
     envelope: {
-        version: 1;
+        version: 2;
         publicKey: string;
         algorithm: "xchacha20poly1305";
-        entropyNonce: string;
-        sealedEntropy: string;
+        secretKind: "mnemonic-entropy" | "raw-private-key";
+        secretNonce: string;
+        sealedSecret: string;
         wraps: {
             credentialId: string;
             createdAt: string;
             nonce: string;
             wrappedKey: string;
+            rpId: string;
+            verifiedAt?: string | undefined;
         }[];
     };
-    link: {
-        signature: string;
-        timestamp: number;
+    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 WebIdentityWrap = z.infer<typeof webIdentityWrapSchema>;
 export type WebIdentityEnvelope = z.infer<typeof webIdentityEnvelopeSchema>;
+export type WebIdentityHolder = z.infer<typeof webIdentityHolderSchema>;
+export type WebIdentityEnvelopeAction = z.infer<typeof webIdentityEnvelopeActionSchema>;
+export type WebauthnAssertionResponse = z.infer<typeof webauthnAssertionResponseSchema>;
 export type WebIdentityEnvelopeUpload = z.infer<typeof webIdentityEnvelopeUploadSchema>;
 export type WebIdentityEnvelopeResponse = z.infer<typeof webIdentityEnvelopeResponseSchema>;
-export type WebIdentityEnvelopeProof = z.infer<typeof webIdentityEnvelopeProofSchema>;
 export type WebIdentityEnvelopePut = z.infer<typeof webIdentityEnvelopePutSchema>;
 export type WebIdentityEnvelopeEstablish = z.infer<typeof webIdentityEnvelopeEstablishSchema>;