@oxy.so/contracts 4.16.0 → 4.21.0

package/dist/esm/username.js

@@ -99,100 +99,10 @@
  * knows what is taken, and it must not pretend to.
  */
 import { z } from 'zod';
-/** Shortest storable handle. `oxy` sets the floor. */
-export const USERNAME_MIN_LENGTH = 3;
-/** Longest storable handle, and the `maxLength` an input field should carry. */
-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.
- *
- * 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 const USERNAME_PATTERN_SOURCE = '^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$';
-const USERNAME_PATTERN = new RegExp(USERNAME_PATTERN_SOURCE);
+// 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 { USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, RESERVED_USERNAMES, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, BOT_USERNAME_SUFFIX, BOT_USERNAME_INVALID_MESSAGE, RESERVED_USERNAME_SEGMENTS, USERNAME_PATTERN, } from './client/username.js';
+export { USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, RESERVED_USERNAMES, RESERVED_USERNAME_MESSAGE, NUMERIC_USERNAME_MESSAGE, USERNAME_PATTERN_SOURCE, stripDisallowedUsernameCharacters, BOT_USERNAME_SUFFIX, BOT_USERNAME_INVALID_MESSAGE, applyBotUsernameSuffix, } from './client/username.js';
 /**
  * The one username policy, as a schema.
  *
@@ -223,36 +133,6 @@ export const usernameSchema = z
 export function isValidUsername(candidate) {
     return usernameSchema.safeParse(candidate).success;
 }
-/**
- * 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 function stripDisallowedUsernameCharacters(input) {
-    return input.replace(/[^A-Za-z0-9_-]/g, '');
-}
-/**
- * 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 const BOT_USERNAME_SUFFIX = 'bot';
-/** The 400 / inline-validation copy for a bot handle that carries no label. */
-export const BOT_USERNAME_INVALID_MESSAGE = `A bot account's username must end in "${BOT_USERNAME_SUFFIX}"`;
 /**
  * The username policy for an account of kind `bot`: everything above, plus a
  * handle that ends in {@link BOT_USERNAME_SUFFIX}.
@@ -327,27 +207,3 @@ export const botUsernameSchema = usernameSchema.refine((username) => username.to
 export function usernameSchemaForAccountKind(kind) {
     return kind === 'bot' ? botUsernameSchema : usernameSchema;
 }
-/**
- * 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 function applyBotUsernameSuffix(candidate) {
-    const trimmed = candidate.trim();
-    if (trimmed.toLowerCase().endsWith(BOT_USERNAME_SUFFIX)) {
-        return trimmed;
-    }
-    return trimmed.slice(0, USERNAME_MAX_LENGTH - BOT_USERNAME_SUFFIX.length) + BOT_USERNAME_SUFFIX;
-}

package/dist/types/accountAccess.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Wire contract for `GET /internal/accounts/:accountId/access/:userId`: Oxy
+ * answers a trusted first-party service's question "may this person act FOR
+ * that account, and with what?" with no session of that person in the request.
+ *
+ * It exists for the account Oxy never lets anybody act AS: a `channel`
+ * ({@link isDelegatedActAsEligibleKind} refuses it). An app publishes to a
+ * channel with ITS OWN credential, on behalf of a member Oxy vouches for here,
+ * so nobody holds a bearer that speaks as the channel. A long-running import
+ * (Oxy Move) has only a service token and `X-Oxy-User-Id`, which the
+ * user-facing `GET /accounts/:id/members` refuses; this is its answer.
+ *
+ * Needs a service token whose application is platform-trusted AND holds the
+ * privileged {@link ACCOUNTS_MEMBERSHIP_READ_SCOPE}. The answer is always 200:
+ * `access` is `null` for no active membership, an archived account, an unknown
+ * account and an unclaimed directory account alike. Callers must treat every
+ * other status as a refusal (fail closed), and must not cache the answer longer
+ * than the action it authorizes.
+ *
+ * Platform-agnostic — zod only.
+ */
+import { z } from 'zod';
+/**
+ * The scope the endpoint requires.
+ *
+ * Privileged (staff-granted). Channel membership is sensitive because a channel
+ * is anonymous: its members are the people behind a voice that is published
+ * without their names, and "is this person a member of that channel" is
+ * exactly the fact the channel exists to withhold.
+ */
+export declare const ACCOUNTS_MEMBERSHIP_READ_SCOPE: "accounts:membership:read";
+/**
+ * Where the access comes from.
+ *
+ * - `self` — the person IS the account (a personal account asked about itself).
+ * - `direct` — an active membership row on the account.
+ * - `inherited` — an active, cascading membership on an ancestor account.
+ */
+export declare const ACCOUNT_ACCESS_SOURCES: readonly ["self", "direct", "inherited"];
+export type AccountAccessSource = (typeof ACCOUNT_ACCESS_SOURCES)[number];
+export declare const accountAccessSourceSchema: z.ZodEnum<["self", "direct", "inherited"]>;
+/**
+ * One person's EFFECTIVE access over one account.
+ *
+ * `role` and `permissions` are strings rather than closed enums on purpose: the
+ * role and permission vocabularies are the API's, they grow, and a consumer
+ * pinned to an older contracts release must keep reading new ones. Gate on
+ * `permissions` (the role's baseline adjusted by per-member grants and
+ * revokes), never on `role`.
+ */
+export declare const accountAccessGrantSchema: z.ZodObject<{
+    role: z.ZodString;
+    permissions: z.ZodArray<z.ZodString, "many">;
+    /** Only an active membership grants access, so this is the one value. */
+    status: z.ZodLiteral<"active">;
+    source: z.ZodEnum<["self", "direct", "inherited"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "active";
+    role: string;
+    permissions: string[];
+    source: "self" | "direct" | "inherited";
+}, {
+    status: "active";
+    role: string;
+    permissions: string[];
+    source: "self" | "direct" | "inherited";
+}>;
+export type AccountAccessGrant = z.infer<typeof accountAccessGrantSchema>;
+export declare const accountAccessVerdictSchema: z.ZodEffects<z.ZodObject<{
+    accountId: z.ZodString;
+    /** `null` when no such account exists. */
+    kind: z.ZodNullable<z.ZodEnum<["personal", "organization", "project", "bot", "channel"]>>;
+    /** `null` means: this person may not act for this account. */
+    access: z.ZodNullable<z.ZodObject<{
+        role: z.ZodString;
+        permissions: z.ZodArray<z.ZodString, "many">;
+        /** Only an active membership grants access, so this is the one value. */
+        status: z.ZodLiteral<"active">;
+        source: z.ZodEnum<["self", "direct", "inherited"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    }, {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}>, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}, {
+    kind: "organization" | "personal" | "project" | "bot" | "channel" | null;
+    accountId: string;
+    access: {
+        status: "active";
+        role: string;
+        permissions: string[];
+        source: "self" | "direct" | "inherited";
+    } | null;
+}>;
+export type AccountAccessVerdict = z.infer<typeof accountAccessVerdictSchema>;

package/dist/types/accountEmail.d.ts

@@ -13,23 +13,8 @@
  * (`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 declare const EMAIL_VERIFICATION_PURPOSES: readonly ["signup", "signin", "reauth"];
-export type EmailVerificationPurpose = (typeof EMAIL_VERIFICATION_PURPOSES)[number];
-/** Digits in a code. */
-export declare const EMAIL_CODE_LENGTH = 6;
-/** How long a code can be confirmed. */
-export declare const EMAIL_CODE_TTL_MS: number;
-/** Wrong codes before a verification is spent and a new code is needed. */
-export declare const EMAIL_CODE_MAX_ATTEMPTS = 5;
-/** How long a confirmed code's ticket can be spent. */
-export declare const EMAIL_TICKET_TTL_MS: number;
+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';
+export type { EmailVerificationPurpose, EmailVerificationErrorCode } from './client/accountEmail';
 /** An email address as the API stores it: trimmed and lowercase. */
 export declare const emailAddressSchema: z.ZodString;
 /** An opaque one-use ticket (32 random bytes, base64url). */
@@ -39,11 +24,11 @@ export declare const emailVerificationStartRequestSchema: z.ZodObject<{
     purpose: z.ZodLiteral<"signup">;
     email: z.ZodString;
 }, "strict", z.ZodTypeAny, {
-    purpose: "signup";
     email: string;
-}, {
     purpose: "signup";
+}, {
     email: string;
+    purpose: "signup";
 }>;
 export type EmailVerificationStartRequest = z.infer<typeof emailVerificationStartRequestSchema>;
 export interface EmailVerificationStartResponse {
@@ -71,20 +56,3 @@ export interface EmailVerificationConfirmResponse {
     expiresAt: number;
 }
 export declare const emailVerificationConfirmResponseSchema: z.ZodType<EmailVerificationConfirmResponse>;
-/**
- * Stable error codes (`error.code` in the API error body). Clients map these
- * through their localization, never the English message.
- */
-export declare const EMAIL_VERIFICATION_ERROR_CODES: {
-    /** The code is wrong, or its verification expired or was spent. */
-    readonly codeInvalid: "EMAIL_CODE_INVALID";
-    /** Too many wrong codes: request a new one. */
-    readonly tooManyAttempts: "EMAIL_CODE_TOO_MANY_ATTEMPTS";
-    /** The ticket is unknown, expired, spent, or for another email or purpose. */
-    readonly ticketInvalid: "EMAIL_TICKET_INVALID";
-    /** A sign-up without a confirmed email. */
-    readonly ticketRequired: "EMAIL_TICKET_REQUIRED";
-    /** This server cannot send mail. */
-    readonly unavailable: "EMAIL_UNAVAILABLE";
-};
-export type EmailVerificationErrorCode = (typeof EMAIL_VERIFICATION_ERROR_CODES)[keyof typeof EMAIL_VERIFICATION_ERROR_CODES];