@oxy.so/contracts 4.15.0 → 4.17.0

package/dist/esm/accountEmail.js

@@ -13,22 +13,10 @@
  * (`reauth`) use the same code, through their own routes (`signIn.ts`).
  */
 import { z } from 'zod';
-/**
- * - `signup`: above.
- * - `signin`: the code (and link) of an email sign-in (`POST /auth/signin/email/start`).
- * - `reauth`: a signed-in person proving it is them before a sensitive step
- *   (`POST /users/me/reauth/email`): a password, an authenticator, deleting the
- *   account, linking Commons.
- */
-export const EMAIL_VERIFICATION_PURPOSES = ['signup', 'signin', 'reauth'];
-/** Digits in a code. */
-export const EMAIL_CODE_LENGTH = 6;
-/** How long a code can be confirmed. */
-export const EMAIL_CODE_TTL_MS = 10 * 60 * 1000;
-/** Wrong codes before a verification is spent and a new code is needed. */
-export const EMAIL_CODE_MAX_ATTEMPTS = 5;
-/** How long a confirmed code's ticket can be spent. */
-export const EMAIL_TICKET_TTL_MS = 15 * 60 * 1000;
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// it is re-exported here so the root entry is unchanged.
+import { EMAIL_CODE_LENGTH } from './client/accountEmail.js';
+export { EMAIL_VERIFICATION_PURPOSES, EMAIL_CODE_LENGTH, EMAIL_CODE_TTL_MS, EMAIL_CODE_MAX_ATTEMPTS, EMAIL_TICKET_TTL_MS, EMAIL_VERIFICATION_ERROR_CODES, } from './client/accountEmail.js';
 /** An email address as the API stores it: trimmed and lowercase. */
 export const emailAddressSchema = z.string().trim().toLowerCase().min(3).max(254).email();
 /** An opaque one-use ticket (32 random bytes, base64url). */
@@ -58,19 +46,3 @@ export const emailVerificationConfirmResponseSchema = z.object({
     ticket: emailTicketSchema,
     expiresAt: z.number().int().positive(),
 });
-/**
- * Stable error codes (`error.code` in the API error body). Clients map these
- * through their localization, never the English message.
- */
-export const EMAIL_VERIFICATION_ERROR_CODES = {
-    /** The code is wrong, or its verification expired or was spent. */
-    codeInvalid: 'EMAIL_CODE_INVALID',
-    /** Too many wrong codes: request a new one. */
-    tooManyAttempts: 'EMAIL_CODE_TOO_MANY_ATTEMPTS',
-    /** The ticket is unknown, expired, spent, or for another email or purpose. */
-    ticketInvalid: 'EMAIL_TICKET_INVALID',
-    /** A sign-up without a confirmed email. */
-    ticketRequired: 'EMAIL_TICKET_REQUIRED',
-    /** This server cannot send mail. */
-    unavailable: 'EMAIL_UNAVAILABLE',
-};

package/dist/esm/accountGraph.js

@@ -10,239 +10,12 @@ import { z } from 'zod';
 import { avatarCharacterSchema } from './avatarCharacter.js';
 import { ORGANIZATION_TYPES, ORGANIZATION_NAME_MAX_LENGTH, organizationNameSchema, } from './organizations.js';
 import { usernameSchema, usernameSchemaForAccountKind } from './username.js';
-/**
- * The union is spelled out above and the array proves coverage BOTH ways
- * (`satisfies` here, the `Gap` alias below) — the same shape this package's
- * `ACCOUNT_CATEGORY_IDS` / `TRUST_TIERS` pairs use, and the one
- * `db/schema/users.ts` mirrors to keep the `users_kind_check` CHECK honest.
- *
- * Deriving the union from the array instead would cost nothing here and be paid
- * by consumers: `kind` travels into `@oxy.so/services` on every device-directory
- * context (`deviceContextSchema.kind` → `DeviceContext` → the switcher rows),
- * and an indexed-access type is materially more expensive to check there than a
- * literal union.
- */
-export const ACCOUNT_KINDS = [
-    'personal',
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// it is re-exported here so the root entry is unchanged.
+import { ACCOUNT_KINDS, CHILD_ACCOUNT_KINDS, ACCOUNT_CATEGORY_IDS, MAX_ACCOUNT_CATEGORIES, } from './client/accountGraph.js';
+export { ACCOUNT_KINDS, CHILD_ACCOUNT_KINDS, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, isAccountKind, ACCOUNT_CATEGORY_IDS, RETIRED_ACCOUNT_CATEGORY_IDS, isSelectableAccountCategoryId, SELECTABLE_ACCOUNT_CATEGORY_IDS, newlyAddedRetiredCategories, MAX_ACCOUNT_CATEGORIES, ACCOUNT_CATEGORY_KINDS, kindAcceptsAccountCategories, } from './client/accountGraph.js';
 export const accountKindSchema = z.enum(ACCOUNT_KINDS);
-export const CHILD_ACCOUNT_KINDS = [
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
 export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
-/**
- * Whether an account of this kind may be the SUBJECT OF A DELEGATION — an
- * application acting as it on some person's authority. `POST /internal/accounts/
- * :id/service-switch` and the OAuth delegated subject both gate on this.
- *
- * It is NOT the question an account switcher asks. See
- * {@link isOperatorSwitchTargetKind}, and the note below on why the difference
- * is `bot`.
- *
- * Two kinds are refused, for opposite reasons:
- *
- *  - `personal` is a human login, so assuming it would be impersonation.
- *  - `channel` is a CONTENT identity, not an operating one. A channel exists so
- *    that posts can be authored BY it; it is never a seat anybody occupies. Its
- *    operators act on it through their own membership, and an application
- *    publishes to it with its own credential. Refusing act-as is what makes
- *    "no login, ever" structural rather than incidental: no session can be
- *    minted whose subject is a channel, so no bearer exists that could add an
- *    auth method to one (every auth-method write resolves its target from the
- *    authenticated subject, never from a parameter).
- *
- * Consumers must gate on this predicate rather than testing `kind === 'personal'`,
- * which silently admits every kind added after it was written.
- *
- * Being act-as-eligible is NOT being without an identity of one's own. A bot is
- * act-as-eligible AND its own actor (`accountKindActorNature` → `'agent'` in
- * `accountSubject.ts`): an application acting as it on a person's authority
- * records that person as the actor, and the bot acting with nobody operating it
- * records the bot. Neither ever records the bot's owner in the bot's place.
- */
-export function isDelegatedActAsEligibleKind(kind) {
-    return kind === 'organization' || kind === 'project' || kind === 'bot';
-}
-/**
- * Whether a PERSON may switch into an account of this kind — become it, in an
- * account switcher, for the rest of their session.
- *
- * ## Why this is not the same question as {@link isDelegatedActAsEligibleKind}
- *
- * The two differ on exactly one kind, `bot`, and that difference is the whole
- * reason both exist.
- *
- * **A bot is not something you become. It is somebody of its own.** It is an
- * agent's identity, with its own resources, roles, plan and balance, and it is
- * the actor of what it does unoperated. A person may still act AS it on their
- * own authority — that is delegation, recorded with the person as actor, and it
- * is what {@link isDelegatedActAsEligibleKind} admits it for. What a person
- * never does is occupy its seat. This is a refusal of a SEAT, not a capability
- * restriction: nothing a bot may do depends on this predicate.
- *
- * Handing a person the bot's seat instead inverts that. It puts a human inside
- * the identity that exists to act without one, and it does so on the human's own
- * device, next to their personal login — which is precisely what happened: a
- * `bot` account held a live session on a person's device, offered to them by a
- * switcher that had asked the delegation question by mistake.
- *
- * `channel` is refused here as well, for the reason set out above, and
- * `personal` because assuming somebody else's login is impersonation.
- *
- * ## This is the narrower predicate, deliberately
- *
- * Everything a person may become, a service may also act as; the reverse does
- * not hold. A caller that is unsure which question it is asking wants THIS one:
- * being wrong here withholds an affordance, while being wrong the other way
- * hands out a seat.
- */
-export function isOperatorSwitchTargetKind(kind) {
-    return kind === 'organization' || kind === 'project';
-}
-/**
- * Narrow an unknown value to an {@link AccountKind}.
- *
- * The user-DTO serializers read from structurally-permissive `unknown` sources
- * (a Drizzle row, a raw document, an already-formatted object), so each one
- * would otherwise hand-roll this check and they would drift on what counts.
- */
-export function isAccountKind(value) {
-    return typeof value === 'string' && ACCOUNT_KINDS.includes(value);
-}
-// ===========================================================================
-// Account categories
-//
-// Four rules govern this taxonomy. Each one is here because the obvious
-// alternative fails silently rather than loudly.
-//
-// 1. AN ID IS AN OPAQUE, IMMUTABLE SLUG — the LABEL is not stored anywhere.
-//    Every value below is an identifier that no rename may ever change. The
-//    human-readable label lives in each client's own translation catalogue,
-//    keyed by the id. Re-labelling `agency` from "Real estate agency" to
-//    "Agency" is therefore a one-line locale edit that touches no row; moving
-//    the label into the column or the DTO would make the same edit a data
-//    migration, and would pin every reader to the language of whoever chose it.
-//
-// 2. THE PRIMARY CATEGORY IS THE FIRST ELEMENT of an ordered list. Not a
-//    separate flag, and not a second field: a flag admits two primaries and
-//    admits none, and ordering makes both unrepresentable. The cost is that
-//    ORDER IS DATA — anything that re-serializes, sorts or de-duplicates this
-//    list can change which category is primary without erroring, so no layer
-//    between the column and the client may reorder it.
-//
-// 3. THE VOCABULARY IS APPEND-ONLY. `ACCOUNT_CATEGORY_IDS` may gain ids and may
-//    never lose one, because rows already carry the ids it holds. Withdrawing a
-//    category means listing it in {@link RETIRED_ACCOUNT_CATEGORY_IDS}, which
-//    removes it from the picker while leaving it readable and re-writable. The
-//    database enforces the same asymmetry: its CHECK is re-evaluated on EVERY
-//    update to a row, so narrowing the allowed set makes an unrelated write —
-//    saving a bio — fail on any account that had picked the withdrawn value.
-//    Measured on a real Postgres, `NOT VALID` included; it does not help.
-//
-// 4. THE SET IS CLOSED. An id nobody can validate is an id no client can render:
-//    the label comes from a translation key derived from the id, so an invented
-//    value paints as a blank or a raw slug in every app at once. Closing it also
-//    costs nothing that rule 3 does not already charge — adding a category needs
-//    a migration to widen the CHECK whether or not the enum exists, so an open
-//    list would buy back no work, only the validation.
-// ===========================================================================
-/**
- * Every account category, by stable id.
- *
- * Grouped by comment for readability only; the storage, the wire and the picker
- * all treat this as one flat list. `other` is the escape hatch for an account
- * that fits nothing here.
- *
- * TO ADD ONE: append an id (lowercase ASCII, `snake_case`) here, publish
- * `@oxy.so/contracts`, then ship a migration that widens
- * `users_account_categories_check` — never edit an existing migration — and add
- * an `accounts.accountCategory.<id>` label to each client's locales.
- *
- * TO WITHDRAW ONE: leave the id here and add it to
- * {@link RETIRED_ACCOUNT_CATEGORY_IDS}. See rule 3 above.
- */
-export const ACCOUNT_CATEGORY_IDS = [
-    // ---- media & public information -----------------------------------------
-    'news',
-    'politics',
-    // ---- business & economy --------------------------------------------------
-    'business',
-    'startup',
-    'finance',
-    'crypto',
-    'marketplace',
-    'retail',
-    // The four ids the single-valued `organizationCategory` field used to hold,
-    // carried forward VERBATIM. Their labels may be rewritten freely; their ids
-    // may not, because live rows hold them.
-    'real_estate',
-    'agency',
-    'landlord',
-    'cooperative',
-    'architecture',
-    // ---- technology ----------------------------------------------------------
-    'technology',
-    'software',
-    'ai',
-    'security',
-    'automation',
-    // ---- knowledge -----------------------------------------------------------
-    'science',
-    'education',
-    'books',
-    // ---- health --------------------------------------------------------------
-    'health',
-    'fitness',
-    // ---- sport & play --------------------------------------------------------
-    'sports',
-    'gaming',
-    // ---- culture & entertainment ---------------------------------------------
-    //
-    // There is deliberately NO generic `entertainment` here, and re-adding one is
-    // a regression rather than a gap. It is the only id this list ever carried
-    // that was dominated by its own specifics — `film`, `music`, `gaming` and
-    // `comedy` all exist — and a generic drawer sitting beside its four
-    // concretions collects the lazy pick, which degrades the data for all four at
-    // once: the accounts that would have said `film` say `entertainment` instead,
-    // and `film` stops meaning what it meant.
-    //
-    // The other overlaps in this vocabulary are NOT the same case and must not be
-    // merged on this reasoning: `sports`/`fitness`, `art`/`photography`,
-    // `business`/`startup`, `finance`/`crypto`, `home_garden`/`diy` and
-    // `technology`/`software`/`security` are genuinely different audiences, and
-    // with a cap of four the granularity is cheap.
-    'music',
-    'film',
-    'podcast',
-    'art',
-    'photography',
-    'comedy',
-    // ---- everyday life -------------------------------------------------------
-    'food',
-    'travel',
-    'fashion',
-    'home_garden',
-    'diy',
-    'automotive',
-    'animals',
-    'family',
-    // ---- society -------------------------------------------------------------
-    'nonprofit',
-    'government',
-    'community',
-    'activism',
-    'environment',
-    'religion',
-    // ---- fallback ------------------------------------------------------------
-    'other',
-];
 /**
  * Accepts EVERY id, withdrawn ones included — see rule 3.
  *
@@ -252,59 +25,6 @@ export const ACCOUNT_CATEGORY_IDS = [
  * nullable `bio` / `avatar` fix addressed, wearing a different hat.
  */
 export const accountCategoryIdSchema = z.enum(ACCOUNT_CATEGORY_IDS);
-/**
- * Ids withdrawn from the picker. Empty today.
- *
- * A withdrawn id keeps working everywhere it is already stored: it validates,
- * it survives a round-trip save, it still renders from its label key, and it
- * stays PRIMARY if it was primary. Nothing rewrites a stored list — a read-time
- * or migration-time demotion would silently replace a choice its owner made,
- * which is precisely what stable ids exist to prevent. The owner drops it on
- * their next edit; until then it is honoured.
- *
- * What withdrawal changes is only this: the id leaves
- * {@link SELECTABLE_ACCOUNT_CATEGORY_IDS}, so no picker offers it, and
- * {@link newlyAddedRetiredCategories} refuses to let a write ADD it to an
- * account that did not already have it.
- */
-export const RETIRED_ACCOUNT_CATEGORY_IDS = [];
-/** Whether a category may still be OFFERED. A stored one is readable either way. */
-export function isSelectableAccountCategoryId(id) {
-    return !RETIRED_ACCOUNT_CATEGORY_IDS.includes(id);
-}
-/** The ids a picker may offer, in declaration order. */
-export const SELECTABLE_ACCOUNT_CATEGORY_IDS = ACCOUNT_CATEGORY_IDS.filter(isSelectableAccountCategoryId);
-/**
- * Which of `next` are withdrawn ids the account did not already carry — i.e.
- * the ones a write must be refused for.
- *
- * `retired` is a parameter rather than a module read so the rule can be
- * exercised against a non-empty set while the production one is empty; a test
- * over `RETIRED_ACCOUNT_CATEGORY_IDS` alone would pass vacuously today and stay
- * passing if the rule were deleted.
- */
-export function newlyAddedRetiredCategories(next, previous, retired) {
-    return next.filter((id) => retired.includes(id) && !previous.includes(id));
-}
-/**
- * How many categories one account may carry.
- *
- * Four, not "as many as you like". Three reasons, in the order they bind:
- *
- *  - The primary has to MEAN something. At ten categories the first element
- *    reads as a sort artifact rather than a choice, and rule 2 above is the
- *    entire mechanism by which a primary exists.
- *  - The profile RENDERS them as a row of chips; four labels of this length is
- *    what fits a phone-width profile header before the row wraps or truncates.
- *  - Four is enough to place a genuinely compound account without a tag cloud:
- *    a housing cooperative that is also a non-profit serving a local community
- *    spends `cooperative`, `nonprofit`, `community`, `real_estate` — and is the
- *    most compound real example in the ecosystem.
- *
- * One constant, read by the wire schema, the database CHECK and the picker, so
- * changing it is one edit plus a migration.
- */
-export const MAX_ACCOUNT_CATEGORIES = 4;
 /**
  * An account's categories on the wire. ORDER IS MEANINGFUL — index 0 is the
  * primary (rule 2).
@@ -331,31 +51,6 @@ export const accountCategoriesSchema = z
         seen.add(id);
     });
 });
-/**
- * Kinds that may carry categories: every kind EXCEPT `personal`.
- *
- * A person has interests, not a sector — and their interests are not a
- * classification anybody else gets to read off their profile. Spelled out
- * positively, like {@link isDelegatedActAsEligibleKind} and for the same reason: a `kind
- * !== 'personal'` test silently admits every kind invented after it was
- * written, whereas this list forces whoever adds one to decide.
- */
-export const ACCOUNT_CATEGORY_KINDS = [
-    'organization',
-    'project',
-    'bot',
-    'channel',
-];
-/**
- * Whether an account of this kind may carry categories.
- *
- * The API refuses the write and the `users_account_categories_kind_check`
- * constraint makes it unrepresentable; both derive from
- * {@link ACCOUNT_CATEGORY_KINDS}, so they cannot disagree.
- */
-export function kindAcceptsAccountCategories(kind) {
-    return ACCOUNT_CATEGORY_KINDS.includes(kind ?? '');
-}
 /**
  * An account's name on the create/update wire.
  *

package/dist/esm/agentKeys.js

@@ -2,15 +2,10 @@
 import { z } from 'zod';
 import { reauthProofSchema } from './signIn.js';
 import { canonicalJson } from './identityProof.js';
-export const AGENT_PROOF_AUDIENCE = 'oxy-api/agent';
-export const AGENT_PROOF_TTL_MS = 60000;
-export const AGENT_PROOF_ACTIONS = [
-    'agent_signin',
-    'agent_enroll',
-    'agent_rotate',
-    'agent_recover',
-    'agent_governance',
-];
+// The Zod-free half of this contract lives in `./client/` (`@oxy.so/contracts/client`);
+// it is re-exported here so the root entry is unchanged.
+import { AGENT_PROOF_AUDIENCE, AGENT_PROOF_ACTIONS } from './client/agentKeys.js';
+export { AGENT_PROOF_AUDIENCE, AGENT_PROOF_TTL_MS, AGENT_PROOF_ACTIONS, ACCOUNT_AUTH_METHODS, } from './client/agentKeys.js';
 export const agentProofClaimsSchema = z
     .object({
     version: z.literal(1),
@@ -97,7 +92,6 @@ export const agentKeyOperationResultSchema = z
     revokedMethodIds: z.array(z.string()),
 })
     .strict();
-export const ACCOUNT_AUTH_METHODS = ['identity', 'agent_key'];
 /** Public credential inventory. Never includes a proof, bearer or private key. */
 export const agentKeyListResponseSchema = z
     .object({

package/dist/esm/client/accountEmail.js

@@ -0,0 +1,45 @@
+/**
+ * Account-email constants and response checks, without Zod. Schemas: `../accountEmail.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { email, exact, int, maxLength, minLength, number, object, pattern, positive, string, toLowerCase, trim, } from './check.js';
+/**
+ * - `signup`: above.
+ * - `signin`: the code (and link) of an email sign-in (`POST /auth/signin/email/start`).
+ * - `reauth`: a signed-in person proving it is them before a sensitive step
+ *   (`POST /users/me/reauth/email`): a password, an authenticator, deleting the
+ *   account, linking Commons.
+ */
+export const EMAIL_VERIFICATION_PURPOSES = ['signup', 'signin', 'reauth'];
+/** Digits in a code. */
+export const EMAIL_CODE_LENGTH = 6;
+/** How long a code can be confirmed. */
+export const EMAIL_CODE_TTL_MS = 10 * 60 * 1000;
+/** Wrong codes before a verification is spent and a new code is needed. */
+export const EMAIL_CODE_MAX_ATTEMPTS = 5;
+/** How long a confirmed code's ticket can be spent. */
+export const EMAIL_TICKET_TTL_MS = 15 * 60 * 1000;
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+export const EMAIL_VERIFICATION_ERROR_CODES = {
+    /** The code is wrong, or its verification expired or was spent. */
+    codeInvalid: 'EMAIL_CODE_INVALID',
+    /** Too many wrong codes: request a new one. */
+    tooManyAttempts: 'EMAIL_CODE_TOO_MANY_ATTEMPTS',
+    /** The ticket is unknown, expired, spent, or for another email or purpose. */
+    ticketInvalid: 'EMAIL_TICKET_INVALID',
+    /** A sign-up without a confirmed email. */
+    ticketRequired: 'EMAIL_TICKET_REQUIRED',
+    /** This server cannot send mail. */
+    unavailable: 'EMAIL_UNAVAILABLE',
+};
+/* -------------------------------------------------------------------------- */
+/*  Checks                                                                    */
+/* -------------------------------------------------------------------------- */
+export const emailAddressCheck = string(trim, toLowerCase, minLength(3), maxLength(254), email);
+export const emailTicketCheck = string(trim, pattern(/^[A-Za-z0-9_-]{43}$/, 'ticket must be 32 bytes of base64url'));
+export const emailVerificationStartResponseCheck = exact()(object({ verificationId: string(minLength(1), maxLength(64)), expiresAt: number(int, positive) }));
+export const emailVerificationConfirmResponseCheck = exact()(object({ ticket: emailTicketCheck, expiresAt: number(int, positive) }));