@oxy.so/contracts 1.1.1 → 1.3.0

package/dist/esm/userResponse.js

@@ -47,6 +47,60 @@ export const themePreferenceSchema = z.object({
     mode: z.enum(['light', 'dark', 'system']),
     colorPreset: z.string(),
 });
+/**
+ * The earliest calendar year `dateOfBirthSchema` accepts.
+ *
+ * Not a real biological bound — it exists to catch an obviously-transposed
+ * year (`1027` for `2027`, a stray OCR/typo digit) with a clear message
+ * instead of the value quietly becoming a 150-year-old account. 1900 is
+ * generous enough that no living person's real birthdate is rejected by it.
+ */
+const MIN_BIRTH_YEAR = 1900;
+/**
+ * `true` when `year`/`month`/`day` name a date that actually exists on the
+ * Gregorian calendar — the check `z.string().regex(...)` alone cannot make,
+ * since the regex only constrains digit COUNT and would pass `2024-02-30`.
+ */
+function isRealCalendarDate(year, month, day) {
+    const isLeapYear = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const daysInMonth = [31, isLeapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    return month >= 1 && month <= 12 && day >= 1 && day <= daysInMonth[month - 1];
+}
+/**
+ * A date of birth, `YYYY-MM-DD`, the sole structured representation this
+ * platform stores going forward (`users.date_of_birth` — see
+ * `packages/api/src/db/schema/users.ts`). `birthday` (below) stays as the
+ * legacy free-text field for backward compatibility with existing readers;
+ * this schema is what both the write path (`user.service.ts`) and the read
+ * path (nothing — a date of birth is owner-only, never echoed to another
+ * viewer) validate against.
+ *
+ * Three checks, in order, because a regex alone would accept a string-shaped
+ * lie:
+ *  1. Exactly `YYYY-MM-DD` — the wire format, nothing looser.
+ *  2. A real Gregorian date — rejects `2024-02-30`, a date the regex cannot see
+ *     is impossible.
+ *  3. Bounded to a plausible human lifetime — not before {@link MIN_BIRTH_YEAR}
+ *     and not after today (comparing the zero-padded ISO strings directly is
+ *     a valid, simpler stand-in for a numeric comparison here, since two
+ *     `YYYY-MM-DD` strings of equal length sort exactly the way their dates
+ *     do). "Today" is UTC — see `computeIsAdult` in `user.service.ts` for why
+ *     a date with no timezone of its own is evaluated in UTC rather than any
+ *     particular caller's local zone.
+ */
+export const dateOfBirthSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'dateOfBirth must be an ISO 8601 calendar date (YYYY-MM-DD)')
+    .refine((value) => {
+    const [year, month, day] = value.split('-').map(Number);
+    return isRealCalendarDate(year, month, day);
+}, { message: 'dateOfBirth is not a real calendar date' })
+    .refine((value) => Number(value.slice(0, 4)) >= MIN_BIRTH_YEAR, {
+    message: `dateOfBirth must not be before ${MIN_BIRTH_YEAR}`,
+})
+    .refine((value) => value <= new Date().toISOString().slice(0, 10), {
+    message: 'dateOfBirth must not be in the future',
+});
 /**
  * The canonical user object emitted by `formatUserResponse`.
  *
@@ -76,6 +130,26 @@ export const userResponseSchema = z
     phone: z.string().optional(),
     address: z.string().optional(),
     birthday: z.string().optional(),
+    /**
+     * Structured date of birth, `YYYY-MM-DD`. Present only on the
+     * account's OWN profile response (`GET /users/me`, `PUT /users/me`
+     * with `includePrivateFields`) — never on another account's profile,
+     * the same visibility `phone`/`address`/`birthday` already have. See
+     * {@link dateOfBirthSchema}.
+     */
+    dateOfBirth: dateOfBirthSchema.optional(),
+    /**
+     * Derived, non-PII signal: whether the account holder is at least 18
+     * (see `computeIsAdult` in `user.service.ts` for the exact threshold
+     * and the UTC-"today" choice). Computed fresh on every read — age
+     * changes daily, so this is never stored. `undefined` when
+     * `dateOfBirth` is unset ("unknown"), distinct from `false` ("known,
+     * not yet 18"). Rides the same owner-only visibility as
+     * `dateOfBirth`; a future pass may widen this specific field to
+     * other viewers without exposing the birthdate itself, but that is
+     * not decided here.
+     */
+    isAdult: z.boolean().optional(),
     /** Avatar file id (string) or null. */
     avatar: z.string().nullable().optional(),
     /** Named Bloom color preset (e.g. `"blue"`) or null. */
@@ -171,6 +245,13 @@ export const userProfileUpdateSchema = z
     phone: z.string().optional(),
     address: z.string().optional(),
     birthday: z.string().optional(),
+    /**
+     * Structured date of birth. `null` (or `''`, at the service layer)
+     * clears it. Independently settable from `birthday` — see
+     * `user.service.ts`'s `updateUserProfile` for why the two legacy and
+     * structured fields are not kept in sync with each other.
+     */
+    dateOfBirth: dateOfBirthSchema.nullable().optional(),
     locations: z.array(z.unknown()).optional(),
     links: z.array(z.string()).optional(),
     linksMetadata: z

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

@@ -0,0 +1,178 @@
+/**
+ * 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

@@ -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,
 });
 /**