@oxy.so/contracts 1.2.0 → 1.3.0

package/dist/esm/username.js

@@ -106,6 +106,71 @@ export const USERNAME_MAX_LENGTH = 30;
 /** The 400 / inline-validation copy for every path that rejects a handle. */
 export const USERNAME_INVALID_MESSAGE = 'Username must be 3-30 characters, use only letters, numbers, hyphens and underscores, ' +
     'start and end with a letter or number, and never repeat a separator';
+/**
+ * Exact-match handles nobody may newly claim, regardless of account kind.
+ *
+ * This is NOT a namespace tightening like the bot suffix — it is a list of
+ * names withheld from `users_lower_username_key` before anybody asks for
+ * them. Compared against the same normalization the unique index applies
+ * (`lower(btrim(username))`), so `Admin`, ` ADMIN ` and `admin` are the one
+ * name this list means.
+ *
+ * `oxy`, `mention`, `homiio`, `clarity`, `faircoin`, `astro` and `mercaria`
+ * are deliberately NOT here: each already has an `organization`/`project`
+ * row, so the unique index already refuses a second one, and `oxy` is the
+ * name `USERNAME_MIN_LENGTH` is pinned against in
+ * `__tests__/username.test.ts` — listing it would make
+ * `usernameSchema.safeParse('oxy')` fail and falsify that comment. A brand
+ * with no account of its own yet (measured 2026-09-18: Alia, Allo, TNP,
+ * Kaana, Bloom) has no row to protect it, so it is listed until one exists.
+ */
+export const RESERVED_USERNAMES = new Set([
+    // Oxy product lines with no account row of their own yet.
+    'alia',
+    'allo',
+    'tnp',
+    'kaana',
+    'bloom',
+    // System / role words a signup impersonating staff or Oxy itself would reach for.
+    'admin',
+    'administrator',
+    'root',
+    'superadmin',
+    'super',
+    'superuser',
+    'support',
+    'staff',
+    'moderator',
+    'mod',
+    'security',
+    'system',
+    'official',
+    'help',
+    'noreply',
+    'anonymous',
+    'everyone',
+    'owner',
+]);
+/** The 400 / inline-validation copy for a handle on {@link RESERVED_USERNAMES}. */
+export const RESERVED_USERNAME_MESSAGE = 'This username is reserved and cannot be registered';
+/**
+ * {@link RESERVED_USERNAMES}, minus `alia`, checked against each `-`/`_`
+ * separated SEGMENT of a candidate rather than the whole string — so
+ * `official-oxy`, `super-admin` and `team-kaana` are refused the same as the
+ * bare words, without banning every word that merely CONTAINS one as a
+ * substring (`superman`, `modern`, `grassroot`, `homeowner` all stay legal:
+ * none of them separates the reserved word from the rest with `-` or `_`).
+ *
+ * `alia` is excluded because `alia-` is the live internal-cost-centre
+ * namespace: `alia-production-chat` is a minted account and
+ * `alia-research` / `alia-voice` / `alia-evaluations` are pinned as legal
+ * slugs in `__tests__/username.test.ts` and `internalCostCenterSpecs.test.ts`.
+ * Segment-matching `alia` would refuse all four. The bare word `alia` is
+ * still refused — {@link RESERVED_USERNAMES} above catches it exactly.
+ */
+const RESERVED_USERNAME_SEGMENTS = new Set([...RESERVED_USERNAMES].filter((word) => word !== 'alia'));
+/** The 400 / inline-validation copy for a handle that is only digits. */
+export const NUMERIC_USERNAME_MESSAGE = 'Username cannot be only numbers';
 /**
  * Alphanumeric runs joined by single separators, as a SOURCE string.
  *
@@ -142,7 +207,10 @@ export const usernameSchema = z
     .trim()
     .min(USERNAME_MIN_LENGTH, USERNAME_INVALID_MESSAGE)
     .max(USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE)
-    .regex(USERNAME_PATTERN, USERNAME_INVALID_MESSAGE);
+    .regex(USERNAME_PATTERN, USERNAME_INVALID_MESSAGE)
+    .refine((username) => !/^[0-9]+$/.test(username), NUMERIC_USERNAME_MESSAGE)
+    .refine((username) => !RESERVED_USERNAMES.has(username.toLowerCase()), RESERVED_USERNAME_MESSAGE)
+    .refine((username) => !username.split(/[-_]/).some((segment) => RESERVED_USERNAME_SEGMENTS.has(segment.toLowerCase())), RESERVED_USERNAME_MESSAGE);
 /**
  * Whether a candidate handle is storable — the boolean form, for input surfaces
  * that show a message as somebody types rather than throwing.

package/dist/esm/webIdentityCarrier.js

@@ -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 const WEB_IDENTITY_ENVELOPE_VERSION = 1;
+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()
@@ -45,6 +47,13 @@ export const webauthnCredentialIdSchema = z
     .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,
@@ -53,6 +62,13 @@ export const webIdentityWrapSchema = 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: 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).
@@ -60,15 +76,27 @@ export const webIdentityWrapSchema = 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.
  */
-export const webIdentityEnvelopeSchema = z.object({
+export const webIdentityEnvelopeSchema = z
+    .object({
     version: z.literal(WEB_IDENTITY_ENVELOPE_VERSION),
     algorithm: z.literal('xchacha20poly1305'),
     publicKey: 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: 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.
@@ -79,41 +107,72 @@ export const webIdentityEnvelopeSchema = z.object({
 export const webIdentityEnvelopeUploadSchema = z.object({
     envelope: 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. */
+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(),
-    /**
-     * 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.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` 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 const webIdentityEnvelopeProofSchema = z.object({
-    signature: z.string().trim().min(1).max(512),
-    timestamp: z.number().int().positive(),
-});
-/** `PUT /identity/web-envelope` body: the envelope plus a `web_envelope_put` identity-key proof. */
-export const webIdentityEnvelopePutSchema = webIdentityEnvelopeUploadSchema.extend(webIdentityEnvelopeProofSchema.shape);
+export const webIdentityEnvelopeActionSchema = webIdentityEnvelopeProofFieldsSchema.strict();
+/** `PUT /identity/web-envelope` body. */
+export const webIdentityEnvelopePutSchema = webIdentityEnvelopeUploadSchema.extend(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.
  */
-export const webIdentityEnvelopeEstablishSchema = webIdentityEnvelopePutSchema.extend({
-    link: webIdentityEnvelopeProofSchema,
-});
+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

@@ -11,6 +11,8 @@
  * 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
@@ -56,6 +58,18 @@ export const webauthnLoginOptionsRequestSchema = z.object({
  */
 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,
 });
 /**