@oxy.so/contracts 4.16.0 → 4.21.0

package/dist/esm/applicationRoles.js

@@ -0,0 +1,207 @@
+/**
+ * Application roles — the wire contract for permissions an APPLICATION declares
+ * about its own users, and for the grants that give them to Oxy users.
+ *
+ * Oxy decides who holds an app's operator powers (who may run Mercaria's
+ * payments desk, moderate GoWay, administer Homiio), so no app keeps an
+ * allow-list of Oxy user ids in its environment. The app declares a closed
+ * vocabulary of keys, its owners grant them to people, and the app's backend
+ * asks Oxy which of them the human behind a request holds
+ * (`GET /applications/:appId/roles/me`, read through `@oxy.so/core/server`).
+ *
+ * ## Why an application key can never collide with an Oxy permission
+ *
+ * Every permission Oxy itself checks (`app:update`, `apps:create`,
+ * `credentials:rotate`, every scope) is spelled with a COLON. An application key
+ * is dot-separated lowercase segments and cannot contain one, so the two
+ * vocabularies are disjoint by syntax, not by convention. They are also stored
+ * apart (scoped to one application id) and no Oxy gate ever reads an
+ * application key. A key means something only to the application that declared
+ * it.
+ *
+ * The pattern is exported as a SOURCE string because the API renders the same
+ * text into a Postgres CHECK; JavaScript's `RegExp` and Postgres' ARE agree on
+ * everything it uses (anchors, classes, a capturing group, a bounded repeat).
+ *
+ * Platform-agnostic — zod only, no react/react-native/expo.
+ */
+import { z } from 'zod';
+/**
+ * Two to four dot-separated segments, each a lowercase letter followed by
+ * lowercase letters, digits or underscores: `payments.operate`,
+ * `catalog.review.publish`. At least two segments so a key always names an
+ * area and an action; never a colon (see the header).
+ */
+export const APPLICATION_PERMISSION_KEY_PATTERN_SOURCE = '^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*){1,3}$';
+export const APPLICATION_PERMISSION_KEY_PATTERN = new RegExp(APPLICATION_PERMISSION_KEY_PATTERN_SOURCE);
+export const APPLICATION_PERMISSION_KEY_MAX_LENGTH = 64;
+export const APPLICATION_PERMISSION_DESCRIPTION_MAX_LENGTH = 280;
+/** How many live keys one application may declare. Operator powers are few. */
+export const APPLICATION_PERMISSIONS_MAX_DECLARED = 64;
+export const APPLICATION_ROLE_REASON_MAX_LENGTH = 500;
+export const APPLICATION_ROLE_GRANTS_PAGE_DEFAULT = 50;
+export const APPLICATION_ROLE_GRANTS_PAGE_MAX = 200;
+/**
+ * The `error` codes the application-roles routes answer beyond the generic
+ * ones (`BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN`, `NOT_FOUND`). Renaming one
+ * is a breaking change.
+ */
+export const APPLICATION_ROLE_ERROR_CODES = {
+    /** 403: a grant naming yourself on an application you do not own outright. */
+    selfGrantForbidden: 'SELF_GRANT_FORBIDDEN',
+    /** 422: the key is not a live declared permission of this application. */
+    unknownPermission: 'UNKNOWN_PERMISSION',
+    /** 422: the grantee is not a person (an organization, project, bot or channel). */
+    granteeNotAPerson: 'GRANTEE_NOT_A_PERSON',
+    /** 409: the grantee already holds the key; `details.grantId` names the live grant. */
+    alreadyGranted: 'ALREADY_GRANTED',
+    /** 409: the grant was already revoked. */
+    alreadyRevoked: 'ALREADY_REVOKED',
+    /** 403: the bearer's session belongs to a DIFFERENT application. */
+    sessionApplicationMismatch: 'SESSION_APPLICATION_MISMATCH',
+};
+/** Whether `value` is a well-formed application permission key. */
+export function isApplicationPermissionKey(value) {
+    return (typeof value === 'string' &&
+        value.length <= APPLICATION_PERMISSION_KEY_MAX_LENGTH &&
+        APPLICATION_PERMISSION_KEY_PATTERN.test(value));
+}
+export const applicationPermissionKeySchema = z
+    .string()
+    .max(APPLICATION_PERMISSION_KEY_MAX_LENGTH)
+    .regex(APPLICATION_PERMISSION_KEY_PATTERN, 'A permission key is 2-4 dot-separated lowercase segments, e.g. payments.operate');
+/** Plain text: no control characters other than a newline or a tab. */
+function plainText(max) {
+    return z
+        .string()
+        .trim()
+        .min(1)
+        .max(max)
+        .refine((value) => Array.from(value).every((character) => {
+        const code = character.charCodeAt(0);
+        return (code >= 32 && code !== 127) || character === '\n' || character === '\t';
+    }), 'Must be plain text');
+}
+const id = z.string().min(1).max(128);
+const isoTimestamp = z.string().min(1);
+const reasonSchema = plainText(APPLICATION_ROLE_REASON_MAX_LENGTH);
+/** One key as the application's owners declare it. */
+export const applicationPermissionDeclarationSchema = z
+    .object({
+    key: applicationPermissionKeySchema,
+    description: plainText(APPLICATION_PERMISSION_DESCRIPTION_MAX_LENGTH),
+})
+    .strict();
+/**
+ * `PUT /applications/:appId/roles/permissions` — the WHOLE vocabulary.
+ *
+ * Declarative: a key present here and not live is added, a live key absent
+ * here is retired (and every grant of it revoked), a live key present here
+ * keeps its identity and takes the new description. Sending the same body twice
+ * changes nothing.
+ */
+export const declareApplicationPermissionsRequestSchema = z
+    .object({
+    permissions: z
+        .array(applicationPermissionDeclarationSchema)
+        .max(APPLICATION_PERMISSIONS_MAX_DECLARED),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const seen = new Set();
+    value.permissions.forEach((permission, index) => {
+        if (seen.has(permission.key)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['permissions', index, 'key'],
+                message: `Duplicate permission key ${permission.key}`,
+            });
+        }
+        seen.add(permission.key);
+    });
+});
+/** A declared key. Retired keys are history: they confer nothing. */
+export const applicationPermissionSchema = z.object({
+    key: applicationPermissionKeySchema,
+    description: z.string(),
+    declaredAt: isoTimestamp,
+    declaredByUserId: id.nullable(),
+    retiredAt: isoTimestamp.nullable(),
+    retiredByUserId: id.nullable(),
+});
+export const applicationPermissionListSchema = z.object({
+    items: z.array(applicationPermissionSchema),
+});
+export const declareApplicationPermissionsResponseSchema = applicationPermissionListSchema.extend({
+    /** Keys that became live with this declaration. */
+    added: z.array(applicationPermissionKeySchema),
+    /** Keys this declaration retired. */
+    retired: z.array(applicationPermissionKeySchema),
+    /** Live keys whose description changed. */
+    described: z.array(applicationPermissionKeySchema),
+    /** Live grants revoked because their key was retired. */
+    revokedGrants: z.number().int().nonnegative(),
+});
+/** One grant of one key to one Oxy user. Revocation is a stamp, never a delete. */
+export const applicationRoleGrantSchema = z.object({
+    id,
+    applicationId: id,
+    permission: applicationPermissionKeySchema,
+    userId: id,
+    /** The grantee's handle, for display. */
+    username: z.string().nullable(),
+    /** The HUMAN who granted it; null once that account was erased. */
+    grantedByUserId: id.nullable(),
+    grantedAt: isoTimestamp,
+    grantReason: z.string().nullable(),
+    revokedAt: isoTimestamp.nullable(),
+    revokedByUserId: id.nullable(),
+    revokeReason: z.string().nullable(),
+});
+export const applicationRoleGrantListSchema = z.object({
+    items: z.array(applicationRoleGrantSchema),
+    nextCursor: z.string().nullable(),
+});
+/** `POST /applications/:appId/roles/grants` — name the grantee by id OR handle. */
+export const createApplicationRoleGrantRequestSchema = z
+    .object({
+    userId: id.optional(),
+    username: z.string().trim().min(1).max(64).optional(),
+    permission: applicationPermissionKeySchema,
+    reason: reasonSchema.optional(),
+})
+    .strict()
+    .refine((value) => (value.userId === undefined) !== (value.username === undefined), {
+    message: 'Name the grantee with exactly one of userId or username',
+    path: ['userId'],
+});
+/** `POST /applications/:appId/roles/grants/:grantId/revoke`. */
+export const revokeApplicationRoleGrantRequestSchema = z
+    .object({
+    reason: reasonSchema.optional(),
+})
+    .strict();
+/** `GET /applications/:appId/roles/grants` query. */
+export const listApplicationRoleGrantsQuerySchema = z
+    .object({
+    permission: applicationPermissionKeySchema.optional(),
+    userId: id.optional(),
+    includeRevoked: z
+        .enum(['true', 'false'])
+        .transform((value) => value === 'true')
+        .optional(),
+    limit: z.coerce.number().int().min(1).max(APPLICATION_ROLE_GRANTS_PAGE_MAX).optional(),
+    cursor: z.string().min(1).max(512).optional(),
+})
+    .strict();
+/**
+ * `GET /applications/:appId/roles/me` — the keys the HUMAN behind the bearer
+ * holds for this application, in no particular order. `userId` is that human
+ * (the operator), which is NOT the account the session speaks as when a person
+ * is acting as an organization.
+ */
+export const applicationRolesMeSchema = z.object({
+    applicationId: id,
+    userId: id,
+    permissions: z.array(applicationPermissionKeySchema),
+});

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) }));

package/dist/esm/client/accountGraph.js

@@ -0,0 +1,314 @@
+/**
+ * Account kinds and categories, without Zod. Schemas: `../accountGraph.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+/**
+ * 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',
+];
+export const CHILD_ACCOUNT_KINDS = [
+    'organization',
+    'project',
+    'bot',
+    'channel',
+];
+/**
+ * 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',
+];
+/**
+ * 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;
+/**
+ * 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 ?? '');
+}

package/dist/esm/client/agentKeys.js

@@ -0,0 +1,74 @@
+/**
+ * Agent-key constants and checks, without Zod. Schemas: `../agentKeys.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { array, boolean, datetime, discriminatedUnion, exact, int, literal, maxLength, minLength, nullable, number, oneOf, optional, pattern, positive, strictObject, string, trim, } from './check.js';
+import { reauthProofCheck } from './signIn.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',
+];
+export const ACCOUNT_AUTH_METHODS = ['identity', 'agent_key'];
+/* -------------------------------------------------------------------------- */
+/*  Checks                                                                    */
+/* -------------------------------------------------------------------------- */
+const hex64 = string(pattern(/^[0-9a-f]{64}$/));
+const hexSignature = string(pattern(/^[0-9a-f]+$/i), maxLength(160));
+const timestamp = number(int, positive);
+const publicKey = string(trim, minLength(1), maxLength(130));
+const label = string(trim, minLength(1), maxLength(120));
+export const agentProofClaimsCheck = exact()(strictObject({
+    version: literal(1),
+    audience: literal(AGENT_PROOF_AUDIENCE),
+    action: oneOf(AGENT_PROOF_ACTIONS),
+    accountId: string(minLength(1)),
+    actorId: string(minLength(1)),
+    authMethodId: nullable(string()),
+    publicKey: string(minLength(1)),
+    payloadDigest: hex64,
+    challenge: hex64,
+    expiresAt: number(int, positive),
+}));
+export const agentChallengeRequestCheck = exact()(strictObject({ publicKey }));
+export const agentVerifyRequestCheck = exact()(strictObject({ challenge: hex64, signature: hexSignature, timestamp, publicKey }));
+export const agentKeyOperationCheck = exact()(discriminatedUnion('operation', {
+    enroll: strictObject({ operation: literal('enroll'), publicKey, label }),
+    recover: strictObject({ operation: literal('recover'), publicKey, label }),
+    rotate: strictObject({
+        operation: literal('rotate'),
+        publicKey,
+        label,
+        retireCurrent: optional(boolean),
+    }),
+    revoke: strictObject({ operation: literal('revoke'), methodId: string(minLength(1)) }),
+}));
+export const executeAgentKeyOperationCheck = exact()(strictObject({
+    operation: agentKeyOperationCheck,
+    proof: strictObject({
+        challenge: hex64,
+        timestamp,
+        keySignature: optional(hexSignature),
+        governorSignature: optional(hexSignature),
+        reauth: optional(reauthProofCheck),
+    }),
+}));
+export const agentKeyOperationChallengeCheck = exact()(strictObject({ claims: agentProofClaimsCheck, governorPublicKey: nullable(string()) }));
+export const agentKeyOperationResultCheck = exact()(strictObject({ methodId: nullable(string()), revokedMethodIds: array(string()) }));
+export const agentKeyListResponseCheck = exact()(strictObject({
+    keys: array(strictObject({
+        id: string(),
+        publicKey: string(),
+        label: string(),
+        enrolledByUserId: nullable(string()),
+        enrollmentMethod: oneOf(['governor', 'rotation', 'recovery']),
+        linkedAt: string(datetime),
+        lastUsedAt: nullable(string(datetime)),
+        revokedAt: nullable(string(datetime)),
+    })),
+}));