@oxy.so/contracts 4.16.0 → 4.21.0

package/dist/types/client/safety.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Safety and supervision checks, without Zod. Schemas: `../safety.ts`.
+ *
+ * Only what a browser or device sends and reads is here: the profile-access
+ * read, supervision management and the guardian's purchase review. The service
+ * decision lanes are server-only (`@oxy.so/core/server`) and parse with the
+ * Zod schemas directly.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import { type Check } from './check';
+/** Supervision is a personal-account safety policy, never a new login/account kind. */
+export declare const SUPERVISED_ACTIONS: readonly ["profile", "messaging", "content", "purchases"];
+export declare const SAFETY_POLICY_VERSION: "2";
+export declare const SUPERVISION_CONSENT_VERSION: "1";
+export declare const SUPERVISION_STATUSES: readonly ["active", "orphaned", "ended"];
+export declare const SUPERVISION_INVITATION_STATUSES: readonly ["pending", "accepted", "cancelled"];
+export declare const PURCHASE_APPROVAL_STATUSES: readonly ["pending", "approved", "rejected", "reserved", "confirmed", "cancelled"];
+export declare const profileAccessInputCheck: Check<{
+    subjectAccountId: string;
+}>;
+export declare const profileAccessDecisionCheck: Check<{
+    allowed: boolean;
+    reason: "owner" | "unavailable" | "public" | "private" | "blocked";
+    policyVersion: "1";
+}>;
+export declare const supervisionInvitationCheck: Check<{
+    status: "pending" | "accepted" | "cancelled";
+    createdAt: string;
+    id: string;
+    expiresAt: string;
+    childAccountId: string;
+    guardianAccountId: string;
+    consentVersion: "1";
+}>;
+export declare const supervisionStateCheck: Check<{
+    self: {
+        status: "active" | "orphaned" | "ended";
+        createdAt: string;
+        policyVersion: "2";
+        childAccountId: string;
+        guardianAccountId: string | null;
+        consentVersion: "1";
+    } | null;
+    children: {
+        status: "active" | "orphaned" | "ended";
+        createdAt: string;
+        policyVersion: "2";
+        childAccountId: string;
+        guardianAccountId: string | null;
+        consentVersion: "1";
+    }[];
+    invitations: {
+        status: "pending" | "accepted" | "cancelled";
+        createdAt: string;
+        id: string;
+        expiresAt: string;
+        childAccountId: string;
+        guardianAccountId: string;
+        consentVersion: "1";
+    }[];
+}>;
+export declare const supervisionContactsResponseCheck: Check<{
+    items: {
+        childAccountId: string;
+        contactAccountId: string;
+        approvedAt: string;
+    }[];
+}>;
+export declare const supervisionInviteInputCheck: Check<{
+    reauth: {
+        password?: string | undefined;
+        emailCode?: {
+            code: string;
+            verificationId: string;
+        } | undefined;
+        totpCode?: string | undefined;
+    };
+    guardianAccountId: string;
+    consentVersion: "1";
+}>;
+export declare const supervisionAcceptInputCheck: Check<{
+    reauth: {
+        password?: string | undefined;
+        emailCode?: {
+            code: string;
+            verificationId: string;
+        } | undefined;
+        totpCode?: string | undefined;
+    };
+    consentVersion: "1";
+}>;
+export declare const supervisionContactInputCheck: Check<{
+    reauth: {
+        password?: string | undefined;
+        emailCode?: {
+            code: string;
+            verificationId: string;
+        } | undefined;
+        totpCode?: string | undefined;
+    };
+    childAccountId: string;
+    contactAccountId: string;
+}>;
+export declare const supervisionReviewInputCheck: Check<{
+    evidenceReference: string;
+    reauth: {
+        password?: string | undefined;
+        emailCode?: {
+            code: string;
+            verificationId: string;
+        } | undefined;
+        totpCode?: string | undefined;
+    };
+    action: "end" | "transfer";
+    childAccountId: string;
+    guardianAccountId?: string | undefined;
+}>;
+export declare const safetyPeopleInputCheck: Check<{
+    query: string;
+} | {
+    accountIds: string[];
+}>;
+export declare const safetyPeopleResponseCheck: Check<{
+    items: {
+        accountId: string;
+        username: string | null;
+        displayName: string | null;
+    }[];
+}>;
+export declare const safetyOrganizationsInputCheck: Check<{
+    query: string;
+    limit?: number | undefined;
+} | {
+    ids: string[];
+}>;
+export declare const safetyOrganizationsResponseCheck: Check<{
+    items: {
+        requestedAccountId: string;
+        organization: {
+            name: string;
+            organizationType: "business" | "nonprofit" | "public_body" | "community" | "other";
+            accountId: string;
+            username: string | null;
+        };
+    }[];
+    missingIds: string[];
+}>;
+export declare const purchaseApprovalCheck: Check<{
+    status: "pending" | "approved" | "rejected" | "cancelled" | "confirmed" | "reserved";
+    createdAt: string;
+    id: string;
+    expiresAt: string;
+    resourceId: string;
+    applicationId: string;
+    currency: string;
+    operationId: string;
+    summary: string;
+    childAccountId: string;
+    cartFingerprint: string;
+    merchantAccountIds: string[];
+    lineItems: {
+        title: string;
+        quantity: number;
+        itemReference: string;
+        optionsText: string;
+        merchantAccountId: string;
+        unitAmountMinor: number;
+        lineAmountMinor: number;
+    }[];
+    shippingMinor: number;
+    taxMinor: number;
+    discountMinor: number;
+    roundingAdjustmentMinor: number;
+    paymentFingerprint: string;
+    amountMinor: number;
+    receiptReference: string | null;
+}>;
+export declare const purchaseApprovalListCheck: Check<{
+    items: {
+        status: "pending" | "approved" | "rejected" | "cancelled" | "confirmed" | "reserved";
+        createdAt: string;
+        id: string;
+        expiresAt: string;
+        resourceId: string;
+        applicationId: string;
+        currency: string;
+        operationId: string;
+        summary: string;
+        childAccountId: string;
+        cartFingerprint: string;
+        merchantAccountIds: string[];
+        shippingMinor: number;
+        taxMinor: number;
+        discountMinor: number;
+        roundingAdjustmentMinor: number;
+        paymentFingerprint: string;
+        amountMinor: number;
+        receiptReference: string | null;
+    }[];
+    nextCursor: string | null;
+}>;
+export declare const purchaseReviewInputCheck: Check<{
+    decision: "approved" | "rejected";
+    reauth: {
+        password?: string | undefined;
+        emailCode?: {
+            code: string;
+            verificationId: string;
+        } | undefined;
+        totpCode?: string | undefined;
+    };
+}>;

package/dist/types/client/sessionStatus.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The public-application check, without Zod. Schemas: `../sessionStatus.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+export declare const publicApplicationCheck: import("./check").Check<{
+    type: "system" | "internal" | "first_party" | "third_party";
+    name: string;
+    id: string;
+    scopes: string[];
+    isOfficial: boolean;
+    isInternal: boolean;
+    websiteUrl?: string | undefined;
+    description?: string | undefined;
+    icon?: string | undefined;
+    privacyPolicyUrl?: string | undefined;
+    termsUrl?: string | undefined;
+    developerName?: string | undefined;
+}>;

package/dist/types/client/signIn.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Sign-in constants, guards and response checks, without Zod. Schemas: `../signIn.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { EmailSignInChooseAccount, EmailSignInLinkResponse, EmailSignInPending, EmailSignInStartResponse, EmailSignInStepResult, SecondFactorRequired, SignInMethods, TotpBackupCodesResponse, TotpEnrollResponse } from '../signIn';
+/** How long the link in a sign-in email can be opened. */
+export declare const EMAIL_SIGNIN_LINK_TTL_MS: number;
+/** How long a second-factor challenge can be answered. */
+export declare const SIGNIN_SECOND_FACTOR_TTL_MS: number;
+/** Wrong second-factor codes one challenge accepts. */
+export declare const SIGNIN_SECOND_FACTOR_MAX_ATTEMPTS = 5;
+/** Shortest password Oxy accepts when one is set. */
+export declare const PASSWORD_MIN_LENGTH = 10;
+/** Longest password Oxy accepts (characters). */
+export declare const PASSWORD_MAX_LENGTH = 256;
+/** Digits in an authenticator code. */
+export declare const TOTP_DIGITS = 6;
+/** Seconds each authenticator code lasts. */
+export declare const TOTP_PERIOD_SECONDS = 30;
+/** Backup codes issued when an authenticator is enabled or they are regenerated. */
+export declare const TOTP_BACKUP_CODE_COUNT = 10;
+/**
+ * The long sign-in code: ten characters of Crockford base32 without the
+ * look-alikes (no 0, O, 1, I, L, U), shown as `XXXXX-XXXXX`. An account whose
+ * sign-in codes were guessed at too often today (the per-account ceiling) is
+ * sent this instead of 6 digits for the rest of the day, so its owner can still
+ * type a code while guessing one is infeasible.
+ */
+export declare const EMAIL_SIGNIN_LONG_CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTVWXYZ";
+export declare const EMAIL_SIGNIN_LONG_CODE_LENGTH = 10;
+/**
+ * Normalise a typed sign-in code: 6 digits stay as they are; a long code is
+ * upper-cased with its dash and spaces removed. Anything else is returned
+ * trimmed (and will simply be wrong).
+ */
+export declare function normalizeEmailSignInCode(code: string): string;
+/**
+ * How long, once the email is proven, the person has to choose which of its
+ * accounts signs in.
+ */
+export declare const EMAIL_SIGNIN_CHOICE_TTL_MS: number;
+/** Most accounts one email can hold; sign-up refuses another past it. */
+export declare const EMAIL_ACCOUNTS_MAX = 20;
+/** Narrow a {@link SignInStepResult}. */
+export declare function isSecondFactorRequired(result: EmailSignInStepResult | EmailSignInPending): result is SecondFactorRequired;
+/** Narrow an {@link EmailSignInStepResult}. */
+export declare function isEmailSignInChooseAccount(result: EmailSignInStepResult | EmailSignInPending): result is EmailSignInChooseAccount;
+/**
+ * What a re-verification email code confirms. The code is bound to it: a code
+ * asked for one change never authorises another, and the email names it.
+ */
+export declare const REAUTH_ACTIONS: readonly ["change_password", "totp", "link_commons", "delete_account", "credentials_manage", "supervision", "supervision_purchase"];
+export type ReauthAction = (typeof REAUTH_ACTIONS)[number];
+/**
+ * Stable error codes (`error.code` in the API error body). Clients map these
+ * through their localization, never the English message.
+ */
+export declare const SIGN_IN_ERROR_CODES: {
+    /** Wrong identifier or password — never says which. */
+    readonly invalidCredentials: "SIGNIN_INVALID_CREDENTIALS";
+    /** The request is unknown, expired, spent, or its secret is wrong. */
+    readonly requestInvalid: "SIGNIN_REQUEST_INVALID";
+    /** The link is unknown, expired or already used. */
+    readonly linkInvalid: "SIGNIN_LINK_INVALID";
+    /** The link was opened in another browser: type the code in the app instead. */
+    readonly linkOtherDevice: "SIGNIN_LINK_OTHER_DEVICE";
+    /** The second-factor challenge or its code is wrong, expired or spent. */
+    readonly secondFactorInvalid: "SECOND_FACTOR_INVALID";
+    /** Too many failures for this account: wait and try again. */
+    readonly locked: "SIGNIN_LOCKED";
+    /** The step needs a fresh proof (`reauth`). */
+    readonly reauthRequired: "REAUTH_REQUIRED";
+    /** The fresh proof was wrong. */
+    readonly reauthInvalid: "REAUTH_INVALID";
+    /** The account has an authenticator: the proof must carry its code. */
+    readonly totpRequired: "TOTP_REQUIRED";
+    /** Enrolling or confirming an authenticator that is already on. */
+    readonly totpAlreadyEnabled: "TOTP_ALREADY_ENABLED";
+    /** Disabling, confirming or regenerating codes with no authenticator (or no pending one). */
+    readonly totpNotEnabled: "TOTP_NOT_ENABLED";
+    /** The code the authenticator showed at enrolment is wrong. */
+    readonly totpCodeInvalid: "TOTP_CODE_INVALID";
+    /** Only official Oxy apps and auth.oxy.so may sign people in here. */
+    readonly originNotAllowed: "SIGNIN_ORIGIN_NOT_ALLOWED";
+    /** The username is taken. */
+    readonly usernameTaken: "USERNAME_TAKEN";
+    /** The email already holds `EMAIL_ACCOUNTS_MAX` accounts: no sign-up adds another. */
+    readonly emailAccountsFull: "EMAIL_ACCOUNTS_FULL";
+};
+export type SignInErrorCode = (typeof SIGN_IN_ERROR_CODES)[keyof typeof SIGN_IN_ERROR_CODES];
+export declare const emailSignInStartResponseCheck: import("./check").Check<EmailSignInStartResponse>;
+export declare const emailSignInLinkResponseCheck: import("./check").Check<EmailSignInLinkResponse>;
+export declare const secondFactorRequiredCheck: import("./check").Check<SecondFactorRequired>;
+export declare const emailSignInPendingCheck: import("./check").Check<EmailSignInPending>;
+export declare const emailSignInChooseAccountCheck: import("./check").Check<EmailSignInChooseAccount>;
+export declare const signInMethodsCheck: import("./check").Check<SignInMethods>;
+export declare const totpEnrollResponseCheck: import("./check").Check<TotpEnrollResponse>;
+export declare const totpBackupCodesResponseCheck: import("./check").Check<TotpBackupCodesResponse>;
+export declare const reauthProofCheck: import("./check").Check<{
+    password?: string | undefined;
+    emailCode?: {
+        code: string;
+        verificationId: string;
+    } | undefined;
+    totpCode?: string | undefined;
+}>;

package/dist/types/client/userResponse.d.ts

@@ -0,0 +1,7 @@
+/**
+ * User-response checks, without Zod. Schemas: `../userResponse.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { UserNameResponse } from '../userResponse';
+export declare const userNameCheck: import("./check").Check<UserNameResponse>;

package/dist/types/client/username.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The username policy, without Zod. Schemas: `../username.ts`.
+ *
+ * Part of `@oxy.so/contracts/client`: never import `zod` here (see `./check.ts`).
+ */
+import type { AccountKind } from './accountGraph';
+import { type Check } from './check';
+/** Shortest storable handle. `oxy` sets the floor. */
+export declare const USERNAME_MIN_LENGTH = 3;
+/** Longest storable handle, and the `maxLength` an input field should carry. */
+export declare const USERNAME_MAX_LENGTH = 30;
+/** The 400 / inline-validation copy for every path that rejects a handle. */
+export declare const USERNAME_INVALID_MESSAGE: string;
+/**
+ * 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 declare const RESERVED_USERNAMES: ReadonlySet<string>;
+/** The 400 / inline-validation copy for a handle on {@link RESERVED_USERNAMES}. */
+export declare 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.
+ */
+export declare const RESERVED_USERNAME_SEGMENTS: ReadonlySet<string>;
+/** The 400 / inline-validation copy for a handle that is only digits. */
+export declare const NUMERIC_USERNAME_MESSAGE = "Username cannot be only numbers";
+/**
+ * Alphanumeric runs joined by single separators, as a SOURCE string.
+ *
+ * A string rather than a literal because the OpenAPI docblocks that publish this
+ * rule (`POST /auth/register`, `PUT /users/:userId`) must quote it verbatim, and
+ * `usernamePolicySingleSource.test.ts` compares them against THIS constant. A
+ * published `pattern:` that drifts from the enforced rule is a lie told to every
+ * client that generates from the spec, and it is exactly the kind of copy nobody
+ * notices going stale.
+ *
+ * Deliberately NOT re-exported from the package barrel: it exists for the
+ * schema below and for that one gate. Anything validating a username uses
+ * {@link usernameSchema}, so there is no second way to ask the question.
+ *
+ * Written as an unambiguous alternation rather than a lookahead: every character
+ * belongs to exactly one branch, so matching is linear and there is no
+ * backtracking to bound. It also carries no `\p{…}` property escape, which
+ * mobile Hermes throws on at runtime — this module is reachable from every React
+ * Native consumer.
+ */
+export declare const USERNAME_PATTERN_SOURCE = "^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$";
+export declare const USERNAME_PATTERN: RegExp;
+/**
+ * Drop the characters the policy forbids, for an input field that filters
+ * keystrokes.
+ *
+ * This is a TYPING aid and nothing else — the result still has to pass
+ * {@link usernameSchema}, which is what decides. It does not lower-case (case is
+ * preserved, see the header) and it cannot repair a name: a value that is too
+ * short, edge-separated or doubly-separated comes back unchanged and fails
+ * validation with a message, which is the outcome the coercing rules this
+ * replaces used to hide.
+ */
+export declare function stripDisallowedUsernameCharacters(input: string): string;
+/**
+ * The label a bot's handle ends in — the ONE exception the policy carries.
+ *
+ * Lower-case here because it is what a generator appends; the comparison that
+ * enforces it folds case, so `MyBot` satisfies it just as `mybot` does.
+ *
+ * Deliberately NOT re-exported from the package barrel, for the same reason
+ * {@link USERNAME_PATTERN_SOURCE} is not: it exists for the schema and the
+ * generator aid below. A consumer that wants to SAY the rule uses
+ * {@link BOT_USERNAME_INVALID_MESSAGE}, which already quotes it, and one that
+ * wants to APPLY it uses {@link applyBotUsernameSuffix} — so there is no second
+ * way to spell the check.
+ */
+export declare const BOT_USERNAME_SUFFIX = "bot";
+/** The 400 / inline-validation copy for a bot handle that carries no label. */
+export declare const BOT_USERNAME_INVALID_MESSAGE = "A bot account's username must end in \"bot\"";
+/**
+ * Label a proposed bot handle, so a generator PROPOSES something the server will
+ * accept.
+ *
+ * Alia builds an agent's handle from its display name; without this it would
+ * propose `garden-helper` for a bot and be 400ed on submit, which is the same
+ * "suggest, then refuse" defect the minimum length already caused once.
+ *
+ * It appends and never inserts: a separator is the caller's choice, so
+ * `garden-helper` becomes `garden-helperbot` while a caller who typed
+ * `garden-helper-` gets `garden-helper-bot`. It truncates to leave room rather
+ * than overflowing {@link USERNAME_MAX_LENGTH}.
+ *
+ * Like {@link stripDisallowedUsernameCharacters} it is an aid, not a decision: it
+ * cannot repair a handle the base policy refuses, and the result still has to
+ * pass {@link botUsernameSchema}.
+ */
+export declare function applyBotUsernameSuffix(candidate: string): string;
+/** The username policy as a check — the twin of `usernameSchema`, same messages. */
+export declare const usernameCheck: Check<string>;
+/** A bot's username: the policy plus the `bot` suffix — the twin of `botUsernameSchema`. */
+export declare const botUsernameCheck: Check<string>;
+/** The twin of `usernameSchemaForAccountKind`. */
+export declare function usernameCheckForAccountKind(kind: AccountKind | null | undefined): Check<string>;