@oxy.so/contracts 1.1.1 → 1.2.0

package/dist/types/webIdentityCarrier.d.ts

@@ -0,0 +1,522 @@
+/**
+ * Web identity carrier contract — "one identity, two carriers".
+ *
+ * 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`).
+ *
+ * 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]
+ *   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.
+ *
+ * Every hex field is lowercase-or-uppercase hex. 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 identity's secp256k1 public key in Oxy's canonical form: uncompressed SEC1
+ * (`04` + 64 bytes), lowercase hex — what `KeyManager.derivePublicKey` produces
+ * and `users.public_key` stores.
+ */
+export declare const webIdentityPublicKeySchema: z.ZodString;
+/** A WebAuthn credential id, base64url as the browser reports it. */
+export declare const webauthnCredentialIdSchema: z.ZodString;
+/** One passkey's wrap of the envelope's data key. */
+export declare const webIdentityWrapSchema: z.ZodObject<{
+    credentialId: z.ZodString;
+    /** 24-byte XChaCha20-Poly1305 nonce. */
+    nonce: z.ZodString;
+    /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+    wrappedKey: z.ZodString;
+    createdAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    credentialId: string;
+    createdAt: string;
+    nonce: string;
+    wrappedKey: string;
+}, {
+    credentialId: string;
+    createdAt: string;
+    nonce: string;
+    wrappedKey: string;
+}>;
+/**
+ * The sealed identity as it is stored (server copy and local copy alike).
+ *
+ * `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>;
+    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;
+    wraps: z.ZodArray<z.ZodObject<{
+        credentialId: z.ZodString;
+        /** 24-byte XChaCha20-Poly1305 nonce. */
+        nonce: z.ZodString;
+        /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+        wrappedKey: z.ZodString;
+        createdAt: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+    }, {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    publicKey: string;
+    algorithm: "xchacha20poly1305";
+    entropyNonce: string;
+    sealedEntropy: string;
+    wraps: {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+    }[];
+}, {
+    version: 1;
+    publicKey: string;
+    algorithm: "xchacha20poly1305";
+    entropyNonce: string;
+    sealedEntropy: string;
+    wraps: {
+        credentialId: string;
+        createdAt: string;
+        nonce: string;
+        wrappedKey: string;
+    }[];
+}>;
+/**
+ * `PUT /identity/web-envelope` — store or replace the caller's envelope.
+ *
+ * Refused unless `envelope.publicKey` is the identity key already linked to the
+ * 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>;
+        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;
+        wraps: z.ZodArray<z.ZodObject<{
+            credentialId: z.ZodString;
+            /** 24-byte XChaCha20-Poly1305 nonce. */
+            nonce: z.ZodString;
+            /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+            wrappedKey: z.ZodString;
+            createdAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+}, {
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+}>;
+/** `GET /identity/web-envelope` — the caller's envelope and its recovery-phrase state. */
+export declare const webIdentityEnvelopeResponseSchema: z.ZodObject<{
+    envelope: z.ZodNullable<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        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;
+        wraps: z.ZodArray<z.ZodObject<{
+            credentialId: z.ZodString;
+            /** 24-byte XChaCha20-Poly1305 nonce. */
+            nonce: z.ZodString;
+            /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+            wrappedKey: z.ZodString;
+            createdAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }>>;
+    /**
+     * 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).
+     */
+    phraseConfirmedAt: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string | null;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    } | null;
+    phraseConfirmedAt: string | null;
+}, {
+    updatedAt: string | null;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    } | null;
+    phraseConfirmedAt: string | null;
+}>;
+/**
+ * `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`.
+ */
+export declare const webIdentityEnvelopeProofSchema: z.ZodObject<{
+    signature: z.ZodString;
+    timestamp: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    timestamp: number;
+}, {
+    signature: string;
+    timestamp: number;
+}>;
+/** `PUT /identity/web-envelope` body: the envelope plus a `web_envelope_put` identity-key proof. */
+export declare const webIdentityEnvelopePutSchema: z.ZodObject<{
+    envelope: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        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;
+        wraps: z.ZodArray<z.ZodObject<{
+            credentialId: z.ZodString;
+            /** 24-byte XChaCha20-Poly1305 nonce. */
+            nonce: z.ZodString;
+            /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+            wrappedKey: z.ZodString;
+            createdAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }>;
+} & {
+    signature: z.ZodString;
+    timestamp: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    timestamp: number;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+}, {
+    signature: string;
+    timestamp: number;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+}>;
+/**
+ * `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.
+ */
+export declare const webIdentityEnvelopeEstablishSchema: z.ZodObject<{
+    envelope: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        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;
+        wraps: z.ZodArray<z.ZodObject<{
+            credentialId: z.ZodString;
+            /** 24-byte XChaCha20-Poly1305 nonce. */
+            nonce: z.ZodString;
+            /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
+            wrappedKey: z.ZodString;
+            createdAt: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }, {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }, {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    }>;
+} & {
+    signature: z.ZodString;
+    timestamp: z.ZodNumber;
+} & {
+    link: z.ZodObject<{
+        signature: z.ZodString;
+        timestamp: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        timestamp: number;
+    }, {
+        signature: string;
+        timestamp: number;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    timestamp: number;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+    link: {
+        signature: string;
+        timestamp: number;
+    };
+}, {
+    signature: string;
+    timestamp: number;
+    envelope: {
+        version: 1;
+        publicKey: string;
+        algorithm: "xchacha20poly1305";
+        entropyNonce: string;
+        sealedEntropy: string;
+        wraps: {
+            credentialId: string;
+            createdAt: string;
+            nonce: string;
+            wrappedKey: string;
+        }[];
+    };
+    link: {
+        signature: string;
+        timestamp: number;
+    };
+}>;
+export type WebIdentityWrap = z.infer<typeof webIdentityWrapSchema>;
+export type WebIdentityEnvelope = z.infer<typeof webIdentityEnvelopeSchema>;
+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>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/contracts",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "OxyHQ API contracts — single source of truth for request/response Zod schemas and inferred types, shared by the backend and the client SDKs",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",