@oxy.so/contracts 2.1.0 → 3.0.0

package/dist/esm/identityRecovery.js

@@ -1,48 +0,0 @@
-/**
- * Signed-out recovery contract (ADR 0024 D5) — get an EXISTING account back from
- * its root alone, with no passkey, session or email.
- *
- *  1. `POST /identity/recovery/challenge` → a one-use challenge. It says nothing
- *     about any account.
- *  2. The holder derives the root locally from recovery material (12/24 words or a
- *     raw key) and signs `recover_account_start` over that challenge:
- *     `POST /identity/recovery/start { publicKey, proof }`. Only a valid proof
- *     learns which account the root belongs to; the response carries passkey
- *     registration options for THAT account and a short-lived ticket.
- *  3. The holder creates the passkey, seals the root under it (PRF), and signs
- *     `recover_account_complete` over the registration challenge and the envelope
- *     digest: `POST /identity/recovery/complete`. The passkey, the envelope and a
- *     session are created in one transaction.
- *
- * The recovery material and the root never leave the holder. Platform-agnostic —
- * zod only, ESM-safe.
- */
-import { z } from 'zod';
-import { identityProofSchema } from './identityProof.js';
-import { webIdentityEnvelopeSchema, webIdentityPublicKeySchema } from './webIdentityCarrier.js';
-/** A recovery attempt lives this long between steps. */
-export const IDENTITY_RECOVERY_TTL_MS = 5 * 60 * 1000;
-export const identityRecoveryChallengeResponseSchema = z.object({
-    challenge: z.string().regex(/^[0-9a-f]{64}$/),
-    expiresAt: z.number().int().positive(),
-});
-export const identityRecoveryStartRequestSchema = z
-    .object({
-    publicKey: webIdentityPublicKeySchema,
-    /** `recover_account_start`, subject `root:<publicKey>`, actor `anonymous`. */
-    proof: identityProofSchema,
-})
-    .strict();
-export const identityRecoveryCompleteRequestSchema = z
-    .object({
-    ticket: z.string().regex(/^[0-9a-f]{64}$/),
-    /** The browser `RegistrationResponseJSON`, verified by the API's WebAuthn library. */
-    response: z.record(z.string(), z.unknown()),
-    /** The root sealed under the new passkey — exactly one wrap, for that credential. */
-    envelope: webIdentityEnvelopeSchema,
-    /** `recover_account_complete`, subject = account id, actor `credential:<id>`, challenge = registration challenge (hex). */
-    proof: identityProofSchema,
-    deviceName: z.string().trim().max(100).optional(),
-    deviceFingerprint: z.string().trim().max(512).optional(),
-})
-    .strict();

package/dist/esm/webIdentityCarrier.js

@@ -1,178 +0,0 @@
-/**
- * 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).
- *
- * 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:
- *
- *   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 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.
- *
- * Platform-agnostic — zod only, ESM-safe (no `require()`).
- */
-import { z } from 'zod';
-import { identityProofSchema } from './identityProof.js';
-/** The envelope scheme. A scheme change is a new literal, never a mutation. */
-export 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 const WEB_IDENTITY_SECRET_KINDS = ['mnemonic-entropy', 'raw-private-key'];
-const hex = (bytes, label) => z
-    .string()
-    .trim()
-    .regex(new RegExp(`^[0-9a-fA-F]{${bytes * 2}}$`), `${label} must be ${bytes * 2} hex characters`);
-/**
- * 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 const webIdentityPublicKeySchema = z
-    .string()
-    .trim()
-    .regex(/^04[0-9a-f]{128}$/, 'publicKey must be an uncompressed, lowercase secp256k1 key (130 hex characters)');
-/** A WebAuthn credential id, base64url as the browser reports it. */
-export const webauthnCredentialIdSchema = z
-    .string()
-    .trim()
-    .min(16)
-    .max(1024)
-    .regex(/^[A-Za-z0-9_-]+$/, 'credentialId must be base64url');
-/** A WebAuthn RP ID: a bare registrable host name, lowercase. */
-export const webauthnRpIdSchema = 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. */
-export const webIdentityWrapSchema = z.object({
-    credentialId: webauthnCredentialIdSchema,
-    /** 24-byte XChaCha20-Poly1305 nonce. */
-    nonce: hex(24, 'nonce'),
-    /** The 32-byte DEK sealed under this passkey's KEK, with the 16-byte tag appended (48 bytes). */
-    wrappedKey: hex(48, 'wrappedKey'),
-    createdAt: z.string().datetime(),
-    /** The RP ID the passkey was created under, asserted explicitly by every later ceremony (ADR 0024 D2). */
-    rpId: 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: z.string().datetime().optional(),
-});
-/**
- * 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 const webIdentityEnvelopeSchema = z
-    .object({
-    version: z.literal(WEB_IDENTITY_ENVELOPE_VERSION),
-    algorithm: z.literal('xchacha20poly1305'),
-    publicKey: webIdentityPublicKeySchema,
-    secretKind: z.enum(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: 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: z.array(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.
- *
- * 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 const webIdentityEnvelopeUploadSchema = z.object({
-    envelope: webIdentityEnvelopeSchema,
-});
-/** A root holder as the status read reports it — metadata only, nothing that opens anything. */
-export const webIdentityHolderSchema = z.object({
-    credentialId: webauthnCredentialIdSchema,
-    rpId: webauthnRpIdSchema,
-    verifiedAt: z.string().datetime().nullable(),
-    createdAt: 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.
- */
-export const webIdentityEnvelopeResponseSchema = z.object({
-    envelope: webIdentityEnvelopeSchema.nullable(),
-    /** The revision a write must name as `expectedRevision`; `0` when there is no envelope. */
-    revision: z.number().int().nonnegative(),
-    /** Whether the account has a linked root at all (it may live only in Commons). */
-    rootLinked: z.boolean(),
-    /** The web wraps, as metadata. */
-    holders: z.array(webIdentityHolderSchema),
-    /** When the owner confirmed the recovery material is written down, or `null`. */
-    phraseConfirmedAt: z.string().datetime().nullable(),
-    /** When the recovery material was shown to re-derive this root, or `null`. */
-    recoveryVerifiedAt: z.string().datetime().nullable(),
-    updatedAt: z.string().datetime().nullable(),
-});
-/** A root proof, plus the envelope revision the write expects to replace. */
-export const webIdentityEnvelopeProofFieldsSchema = z.object({
-    proof: identityProofSchema,
-    expectedRevision: z.number().int().nonnegative(),
-});
-/**
- * `POST /identity/web-envelope/phrase-confirmed`, `/recovery-verified` and
- * `DELETE /identity/web-envelope` prove control of the root, not just a bearer.
- */
-export const webIdentityEnvelopeActionSchema = webIdentityEnvelopeProofFieldsSchema.strict();
-/** `PUT /identity/web-envelope` body. */
-export const webIdentityEnvelopePutSchema = webIdentityEnvelopeUploadSchema.extend(webIdentityEnvelopeProofFieldsSchema.shape).strict();
-/**
- * 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 const webauthnAssertionResponseSchema = z
-    .object({
-    id: webauthnCredentialIdSchema,
-    rawId: z.string().min(1).max(2048),
-    type: z.literal('public-key'),
-    response: z
-        .object({
-        clientDataJSON: z.string().min(1).max(8192),
-        authenticatorData: z.string().min(1).max(8192),
-        signature: z.string().min(1).max(2048),
-        userHandle: z.string().max(2048).optional(),
-    })
-        .passthrough(),
-    clientExtensionResults: z.record(z.string(), z.unknown()).optional(),
-    authenticatorAttachment: 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.
- */
-export const webIdentityEnvelopeEstablishSchema = webIdentityEnvelopeUploadSchema
-    .extend({ proof: identityProofSchema, assertion: webauthnAssertionResponseSchema })
-    .strict();

package/dist/esm/webauthn.js

@@ -1,82 +0,0 @@
-/**
- * WebAuthn / passkey ceremony contracts (Fase B/b1).
- *
- * These schemas describe ONLY the outer Oxy envelope that wraps a WebAuthn
- * ceremony request — the username the client is registering/authenticating as,
- * plus non-authoritative device metadata. The browser
- * `RegistrationResponseJSON` / `AuthenticationResponseJSON` payloads are NOT
- * mirrored here: they are validated by `@simplewebauthn/server` inside the route
- * (`verifyRegistrationResponse` / `verifyAuthenticationResponse`), which is the
- * single source of truth for their structure. Re-encoding them in Zod would just
- * create a second, drift-prone definition of a shape we do not own.
- */
-import { z } from 'zod';
-import { identityProofSchema } from './identityProof.js';
-import { webIdentityEnvelopeSchema } from './webIdentityCarrier.js';
-/**
- * Device-session options shared by every first-party sign-in body
- * (`deviceName`/`deviceFingerprint`). Mirrors what
- * `sessionCreateOptionsFromBody` reads in the API so a WebAuthn login/verify can
- * name its resulting session exactly like `/auth/login` or `/auth/verify`.
- *
- * There is deliberately no `deviceId` here. `createSession` treats an explicit
- * device id as authoritative — `deviceId > stableDeviceKey > UA/IP > random` —
- * and stamps it verbatim, so on an UNAUTHENTICATED sign-in body it is a caller
- * naming somebody else's device and having a session, and then a device secret,
- * minted against it. The legitimate callers that pin a device id are
- * server-side and already authorized (the account-switch route threading the
- * operator's own central device id); they pass it to `createSession` directly
- * and never through a request body.
- */
-const deviceSessionEnvelope = {
-    deviceName: z.string().trim().min(1).max(120).optional(),
-    deviceFingerprint: z.string().trim().min(1).max(256).optional(),
-};
-/**
- * `POST /webauthn/register/options` — request registration options. With a bearer
- * token the caller links a passkey to their signed-in account and `username` is
- * ignored; without one it is a prospective signup and `username` is the desired
- * (not-yet-created) handle.
- */
-export const webauthnRegisterOptionsRequestSchema = z.object({
-    username: z.string().trim().min(1).max(60).optional(),
-});
-/**
- * `POST /webauthn/login/options` — request authentication options. When
- * `username` is present the server scopes `allowCredentials` to that user's
- * passkeys (username-first); when omitted it returns an empty allow-list for the
- * usernameless / discoverable-credential flow (the default).
- */
-export const webauthnLoginOptionsRequestSchema = z.object({
-    username: z.string().trim().min(1).max(60).optional(),
-});
-/**
- * `POST /webauthn/register/verify` — the outer envelope. The browser
- * `RegistrationResponseJSON` travels alongside these fields under `response` and
- * is validated by `@simplewebauthn/server`, not here. `username` is required only
- * for the prospective-signup branch (no bearer); the linking branch ignores it.
- */
-export const webauthnRegisterVerifyRequestSchema = z.object({
-    username: 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: z
-        .object({
-        envelope: webIdentityEnvelopeSchema,
-        proof: identityProofSchema,
-    })
-        .optional(),
-    ...deviceSessionEnvelope,
-});
-/**
- * `POST /webauthn/login/verify` — the outer envelope. The browser
- * `AuthenticationResponseJSON` travels alongside these fields under `response`
- * and is validated by `@simplewebauthn/server`, not here.
- */
-export const webauthnLoginVerifyRequestSchema = z.object({
-    ...deviceSessionEnvelope,
-});

package/dist/types/identityMove.d.ts

@@ -1,185 +0,0 @@
-/**
- * Identity move contract — give a web root to Commons (add it, or keep it only in
- * Commons; ADR 0024 D6).
- *
- * The web (holding the root) shows a QR carrying only a move id; Commons scans.
- * The relay in between must not be able to take the root, so:
- *
- *  1. `POST /identity/move { initiatorCommitment }` — the web publishes only
- *     `H(initiatorKey, nonce)`, never the key.
- *  2. `POST /identity/move/:moveId/join { responderEphemeralPublicKey }` —
- *     Commons, having read the commitment first, joins with its own key.
- *  3. `POST /identity/move/:moveId/reveal` — only then does the web reveal its
- *     key and nonce; Commons checks them against the commitment it read.
- *  4. Both screens show a 6-digit code over `(moveId, both keys, commitment)`;
- *     the person confirms on the web that they match.
- *  5. `POST /identity/move/:moveId/seal` — the web seals the phrase entropy under
- *     `HKDF(ECDH(both keys), moveId)`, authorized by a one-use root proof over the
- *     exact sealed bytes.
- *  6. `POST /identity/move/:moveId/receipt` — Commons stores the root, reads it
- *     back from its keychain, and signs a receipt over the move, the root, both
- *     keys and the digest of the ciphertext it opened. The server verifies it; the
- *     web verifies it again from what IT sealed before removing anything.
- *
- * Why the commitment: without it the relay sees both keys before committing to
- * anything and can grind a substituted key until the two codes agree (~10⁶
- * tries, seconds). With it, the relay must fix the key it shows Commons before
- * learning Commons' key, and the key it shows the web before the web reveals.
- *
- * The server holds a commitment, two ephemeral public keys, an opaque ciphertext
- * and a receipt — nothing that decrypts the ciphertext.
- *
- * Platform-agnostic — zod only, ESM-safe (no `require()`).
- */
-import { z } from 'zod';
-/** A move lives this long: one interactive handoff. */
-export declare const IDENTITY_MOVE_TTL_MS: number;
-/** 128-bit move id, lowercase hex. */
-export declare const identityMoveIdSchema: z.ZodString;
-/** An ephemeral secp256k1 public key, uncompressed lowercase hex. */
-export declare const identityMoveEphemeralKeySchema: z.ZodString;
-export declare const IDENTITY_MOVE_STATUSES: readonly ["pending", "joined", "sealed", "completed", "cancelled", "expired"];
-export type IdentityMoveStatus = (typeof IDENTITY_MOVE_STATUSES)[number];
-/** The QR payload Commons scans. Carries the move id only. */
-export declare const IDENTITY_MOVE_QR_PREFIX = "oxycommons://move?id=";
-export declare const identityMoveCreateRequestSchema: z.ZodObject<{
-    /** `H(initiator ephemeral key, nonce)` — the key itself is revealed only after Commons joins. */
-    initiatorCommitment: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    initiatorCommitment: string;
-}, {
-    initiatorCommitment: string;
-}>;
-export interface IdentityMoveCreateResponse {
-    moveId: string;
-    expiresAt: string;
-}
-export declare const identityMoveCreateResponseSchema: z.ZodType<IdentityMoveCreateResponse>;
-export declare const identityMoveJoinRequestSchema: z.ZodObject<{
-    responderEphemeralPublicKey: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    responderEphemeralPublicKey: string;
-}, {
-    responderEphemeralPublicKey: string;
-}>;
-/** After Commons joined: the committed key and its nonce. */
-export declare const identityMoveRevealRequestSchema: z.ZodObject<{
-    initiatorEphemeralPublicKey: z.ZodString;
-    commitmentNonce: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    initiatorEphemeralPublicKey: string;
-    commitmentNonce: string;
-}, {
-    initiatorEphemeralPublicKey: string;
-    commitmentNonce: string;
-}>;
-export declare const identityMoveSealRequestSchema: z.ZodObject<{
-    /** 24-byte XChaCha20-Poly1305 nonce, hex. */
-    nonce: z.ZodString;
-    /** The 16–32-byte phrase entropy (12–24 words), tag appended, hex. */
-    ciphertext: z.ZodString;
-    /**
-     * Root proof (`identity_move_seal`), payload `{ moveId, nonce, ciphertext }`,
-     * over a one-use challenge from `POST /identity/proof-challenge`.
-     */
-    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, {
-    proof: {
-        expiresAt: number;
-        signature: string;
-        v: 2;
-        challenge: string;
-    };
-    nonce: string;
-    ciphertext: string;
-}, {
-    proof: {
-        expiresAt: number;
-        signature: string;
-        v: 2;
-        challenge: string;
-    };
-    nonce: string;
-    ciphertext: string;
-}>;
-export declare const identityMoveReceiptRequestSchema: z.ZodObject<{
-    /** Root signature over `buildMoveReceiptMessage(...)`. */
-    signature: z.ZodString;
-}, "strict", z.ZodTypeAny, {
-    signature: string;
-}, {
-    signature: string;
-}>;
-/** `GET /identity/move/:moveId` — everything either side needs, nothing that decrypts. */
-export interface IdentityMoveState {
-    moveId: string;
-    status: IdentityMoveStatus;
-    /** The commitment Commons must read before joining. */
-    initiatorCommitment: string;
-    /** The commitment's nonce, published with the key at reveal. */
-    initiatorCommitmentNonce: string | null;
-    /** The identity being moved (so Commons can check the key it will import). */
-    publicKey: string;
-    /** `null` until the web reveals it, after Commons joined. */
-    initiatorEphemeralPublicKey: string | null;
-    responderEphemeralPublicKey: string | null;
-    nonce: string | null;
-    ciphertext: string | null;
-    receiptSignature: string | null;
-    expiresAt: string;
-}
-export declare const identityMoveStateSchema: z.ZodType<IdentityMoveState>;
-export type IdentityMoveCreateRequest = z.infer<typeof identityMoveCreateRequestSchema>;
-export type IdentityMoveJoinRequest = z.infer<typeof identityMoveJoinRequestSchema>;
-export type IdentityMoveRevealRequest = z.infer<typeof identityMoveRevealRequestSchema>;
-export type IdentityMoveSealRequest = z.infer<typeof identityMoveSealRequestSchema>;
-export type IdentityMoveReceiptRequest = z.infer<typeof identityMoveReceiptRequestSchema>;
-/**
- * The initiator's commitment input, `canonicalJson({ v, purpose, key, nonce })`,
- * which the caller hashes with SHA-256.
- */
-export declare function buildMoveCommitmentInput(initiatorEphemeralPublicKey: string, nonce: string): string;
-/** The bytes both sides hash for the 6-digit code. */
-export declare function buildMoveSasInput(input: {
-    moveId: string;
-    initiatorEphemeralPublicKey: string;
-    responderEphemeralPublicKey: string;
-    initiatorCommitment: string;
-}): string;
-/** The ciphertext digest input the receipt binds: `canonicalJson({ nonce, ciphertext })`. */
-export declare function buildMoveCiphertextDigestInput(sealed: {
-    nonce: string;
-    ciphertext: string;
-}): string;
-/** The payload a seal proof digests. */
-export declare function buildMoveSealPayload(moveId: string, sealed: {
-    nonce: string;
-    ciphertext: string;
-}): {
-    moveId: string;
-    nonce: string;
-    ciphertext: string;
-};
-/** The exact bytes a receipt signs. */
-export declare function buildMoveReceiptMessage(input: {
-    moveId: string;
-    rootPublicKey: string;
-    initiatorEphemeralPublicKey: string;
-    responderEphemeralPublicKey: string;
-    ciphertextDigest: string;
-}): string;