@oxy.so/contracts 1.2.0 → 1.3.0

package/dist/cjs/webIdentityCarrier.js

@@ -1,33 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.webIdentityEnvelopeEstablishSchema = exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeProofSchema = exports.webIdentityEnvelopeResponseSchema = exports.webIdentityEnvelopeUploadSchema = exports.webIdentityEnvelopeSchema = exports.webIdentityWrapSchema = exports.webauthnCredentialIdSchema = exports.webIdentityPublicKeySchema = exports.WEB_IDENTITY_ENVELOPE_VERSION = void 0;
+exports.webIdentityEnvelopeEstablishSchema = exports.webauthnAssertionResponseSchema = exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeActionSchema = exports.webIdentityEnvelopeProofFieldsSchema = exports.webIdentityEnvelopeResponseSchema = exports.webIdentityHolderSchema = exports.webIdentityEnvelopeUploadSchema = exports.webIdentityEnvelopeSchema = exports.webIdentityWrapSchema = exports.webauthnRpIdSchema = exports.webauthnCredentialIdSchema = exports.webIdentityPublicKeySchema = exports.WEB_IDENTITY_SECRET_KINDS = exports.WEB_IDENTITY_ENVELOPE_VERSION = void 0;
 /**
- * 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()`).
  */
 const zod_1 = require("zod");
-/** The only envelope version. A scheme change is a new literal, never a mutation. */
-exports.WEB_IDENTITY_ENVELOPE_VERSION = 1;
+const identityProof_1 = require("./identityProof");
+/** The envelope scheme. A scheme change is a new literal, never a mutation. */
+exports.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.
+ */
+exports.WEB_IDENTITY_SECRET_KINDS = ['mnemonic-entropy', 'raw-private-key'];
 const hex = (bytes, label) => zod_1.z
     .string()
     .trim()
@@ -48,6 +50,13 @@ exports.webauthnCredentialIdSchema = zod_1.z
     .min(16)
     .max(1024)
     .regex(/^[A-Za-z0-9_-]+$/, 'credentialId must be base64url');
+/** A WebAuthn RP ID: a bare registrable host name, lowercase. */
+exports.webauthnRpIdSchema = zod_1.z
+    .string()
+    .trim()
+    .min(1)
+    .max(253)
+    .regex(/^(localhost|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+)$/, 'rpId must be a lowercase host name');
 /** One passkey's wrap of the envelope's data key. */
 exports.webIdentityWrapSchema = zod_1.z.object({
     credentialId: exports.webauthnCredentialIdSchema,
@@ -56,6 +65,13 @@ exports.webIdentityWrapSchema = zod_1.z.object({
     /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
     wrappedKey: hex(48, 'wrappedKey'),
     createdAt: zod_1.z.string().datetime(),
+    /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
+    rpId: exports.webauthnRpIdSchema,
+    /**
+     * 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: zod_1.z.string().datetime().optional(),
 });
 /**
  * The sealed identity as it is stored (server copy and local copy alike).
@@ -63,15 +79,27 @@ exports.webIdentityWrapSchema = zod_1.z.object({
  * `wraps` holds one entry per passkey able to open it; at least one, and a
  * bounded number so an envelope cannot grow without limit.
  */
-exports.webIdentityEnvelopeSchema = zod_1.z.object({
+exports.webIdentityEnvelopeSchema = zod_1.z
+    .object({
     version: zod_1.z.literal(exports.WEB_IDENTITY_ENVELOPE_VERSION),
     algorithm: zod_1.z.literal('xchacha20poly1305'),
     publicKey: exports.webIdentityPublicKeySchema,
-    /** 24-byte nonce of the entropy seal. */
-    entropyNonce: hex(24, 'entropyNonce'),
-    /** The 16-byte BIP-39 entropy sealed under the DEK, tag appended (32 bytes). */
-    sealedEntropy: hex(32, 'sealedEntropy'),
+    secretKind: zod_1.z.enum(exports.WEB_IDENTITY_SECRET_KINDS),
+    /** 24-byte nonce of the secret seal. */
+    secretNonce: hex(24, 'secretNonce'),
+    /**
+     * 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: zod_1.z
+        .string()
+        .trim()
+        .regex(/^(?:[0-9a-fA-F]{64}|[0-9a-fA-F]{72}|[0-9a-fA-F]{80}|[0-9a-fA-F]{88}|[0-9a-fA-F]{96})$/, 'sealedSecret has an unsupported length'),
     wraps: zod_1.z.array(exports.webIdentityWrapSchema).min(1).max(10),
+})
+    .refine((envelope) => envelope.secretKind === 'mnemonic-entropy' || envelope.sealedSecret.length === 96, {
+    message: 'a raw private key seals to 48 bytes',
+    path: ['sealedSecret'],
 });
 /**
  * `PUT /identity/web-envelope` — store or replace the caller's envelope.
@@ -82,41 +110,72 @@ exports.webIdentityEnvelopeSchema = zod_1.z.object({
 exports.webIdentityEnvelopeUploadSchema = zod_1.z.object({
     envelope: exports.webIdentityEnvelopeSchema,
 });
-/** `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. */
+exports.webIdentityHolderSchema = zod_1.z.object({
+    credentialId: exports.webauthnCredentialIdSchema,
+    rpId: exports.webauthnRpIdSchema,
+    verifiedAt: zod_1.z.string().datetime().nullable(),
+    createdAt: zod_1.z.string().datetime(),
+});
+/**
+ * `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.
+ */
 exports.webIdentityEnvelopeResponseSchema = zod_1.z.object({
     envelope: exports.webIdentityEnvelopeSchema.nullable(),
-    /**
-     * 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: zod_1.z.number().int().nonnegative(),
+    /** Whether the account has a linked root at all (it may live only in Commons). */
+    rootLinked: zod_1.z.boolean(),
+    /** The web wraps, as metadata. */
+    holders: zod_1.z.array(exports.webIdentityHolderSchema),
+    /** When the owner confirmed the recovery material is written down, or `null`. */
     phraseConfirmedAt: zod_1.z.string().datetime().nullable(),
+    /** When the recovery material was shown to re-derive this root, or `null`. */
+    recoveryVerifiedAt: zod_1.z.string().datetime().nullable(),
     updatedAt: zod_1.z.string().datetime().nullable(),
 });
+/** A root proof, plus the envelope revision the write expects to replace. */
+exports.webIdentityEnvelopeProofFieldsSchema = zod_1.z.object({
+    proof: identityProof_1.identityProofSchema,
+    expectedRevision: zod_1.z.number().int().nonnegative(),
+});
 /**
- * `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.
  */
-exports.webIdentityEnvelopeProofSchema = zod_1.z.object({
-    signature: zod_1.z.string().trim().min(1).max(512),
-    timestamp: zod_1.z.number().int().positive(),
-});
-/** `PUT /identity/web-envelope` body: the envelope plus a `web_envelope_put` identity-key proof. */
-exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeUploadSchema.extend(exports.webIdentityEnvelopeProofSchema.shape);
+exports.webIdentityEnvelopeActionSchema = exports.webIdentityEnvelopeProofFieldsSchema.strict();
+/** `PUT /identity/web-envelope` body. */
+exports.webIdentityEnvelopePutSchema = exports.webIdentityEnvelopeUploadSchema.extend(exports.webIdentityEnvelopeProofFieldsSchema.shape).strict();
 /**
- * `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.
  */
-exports.webIdentityEnvelopeEstablishSchema = exports.webIdentityEnvelopePutSchema.extend({
-    link: exports.webIdentityEnvelopeProofSchema,
-});
+exports.webauthnAssertionResponseSchema = zod_1.z
+    .object({
+    id: exports.webauthnCredentialIdSchema,
+    rawId: zod_1.z.string().min(1).max(2048),
+    type: zod_1.z.literal('public-key'),
+    response: zod_1.z
+        .object({
+        clientDataJSON: zod_1.z.string().min(1).max(8192),
+        authenticatorData: zod_1.z.string().min(1).max(8192),
+        signature: zod_1.z.string().min(1).max(2048),
+        userHandle: zod_1.z.string().max(2048).optional(),
+    })
+        .passthrough(),
+    clientExtensionResults: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    authenticatorAttachment: zod_1.z.string().optional(),
+})
+    .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.
+ */
+exports.webIdentityEnvelopeEstablishSchema = exports.webIdentityEnvelopeUploadSchema
+    .extend({ proof: identityProof_1.identityProofSchema, assertion: exports.webauthnAssertionResponseSchema })
+    .strict();

package/dist/cjs/webauthn.js

@@ -14,6 +14,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.webauthnLoginVerifyRequestSchema = exports.webauthnRegisterVerifyRequestSchema = exports.webauthnLoginOptionsRequestSchema = exports.webauthnRegisterOptionsRequestSchema = void 0;
 const zod_1 = require("zod");
+const identityProof_1 = require("./identityProof");
+const webIdentityCarrier_1 = require("./webIdentityCarrier");
 /**
  * Device-session options shared by every first-party sign-in body
  * (`deviceName`/`deviceFingerprint`). Mirrors what
@@ -59,6 +61,18 @@ exports.webauthnLoginOptionsRequestSchema = zod_1.z.object({
  */
 exports.webauthnRegisterVerifyRequestSchema = zod_1.z.object({
     username: zod_1.z.string().trim().min(1).max(60).optional(),
+    /**
+     * Sign-up only (ADR 0024 D4): the account's root, created on the holder BEFORE
+     * this request — sealed under the passkey being registered — and a root proof
+     * (`enroll_identity`) whose challenge is the registration challenge. The
+     * account, passkey, root and envelope are then created in one transaction.
+     */
+    identity: zod_1.z
+        .object({
+        envelope: webIdentityCarrier_1.webIdentityEnvelopeSchema,
+        proof: identityProof_1.identityProofSchema,
+    })
+        .optional(),
     ...deviceSessionEnvelope,
 });
 /**