@oxyhq/contracts 0.32.0 → 0.34.0

package/dist/esm/accountGraph.js

@@ -7,6 +7,7 @@
  * {@link ACCOUNT_CATEGORY_IDS} for the four rules that govern it.
  */
 import { z } from 'zod';
+import { usernameSchema } 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
@@ -35,9 +36,13 @@ export const CHILD_ACCOUNT_KINDS = [
 ];
 export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
 /**
- * Whether an operator may ACT AS an account of this kind — switch the whole app
- * into it (`POST /accounts/:id/switch`) or authorise an app to act as it
- * (an OAuth delegated subject).
+ * 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:
  *
@@ -54,9 +59,43 @@ export const childAccountKindSchema = z.enum(CHILD_ACCOUNT_KINDS);
  * Consumers must gate on this predicate rather than testing `kind === 'personal'`,
  * which silently admits every kind added after it was written.
  */
-export function isActAsEligibleKind(kind) {
+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 something that operates on your
+ * behalf.** Its whole purpose is to act while nobody is present: an application
+ * holds a credential, names the human whose authority it borrows, and speaks as
+ * the bot. That is delegation, and it is what
+ * {@link isDelegatedActAsEligibleKind} admits it for.
+ *
+ * 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}.
  *
@@ -287,7 +326,7 @@ export const accountCategoriesSchema = z
  *
  * 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 isActAsEligibleKind} and for the same reason: a `kind
+ * 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.
  */
@@ -342,7 +381,14 @@ const accountNameSchema = z
 export const createAccountRequestSchema = z.object({
     parentAccountId: z.string().trim().min(1).optional(),
     kind: childAccountKindSchema,
-    username: z.string().trim().min(1).max(100),
+    /**
+     * The SAME policy a person's handle is held to. `users.username` is one unique
+     * index, so a managed account may not reserve a name a person could not ask
+     * for — and this route's predecessor (`.min(1).max(100)` here, `^[\w.-]+$`
+     * with no ceiling in the service) is how a one-character or dotted or
+     * 100-character handle became reachable for bots alone.
+     */
+    username: usernameSchema,
     name: accountNameSchema,
     bio: z.string().trim().max(500).optional(),
     avatar: z.string().optional(),

package/dist/esm/index.js

@@ -9,7 +9,8 @@
  * Platform-agnostic — zod is the only runtime dependency. No react/react-native/
  * expo, no `require()` in the ESM build.
  */
-export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isActAsEligibleKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
+export { ACCOUNT_KINDS, accountKindSchema, CHILD_ACCOUNT_KINDS, childAccountKindSchema, isAccountKind, isDelegatedActAsEligibleKind, isOperatorSwitchTargetKind, ACCOUNT_CATEGORY_IDS, ACCOUNT_CATEGORY_KINDS, accountCategoriesSchema, accountCategoryIdSchema, isSelectableAccountCategoryId, kindAcceptsAccountCategories, MAX_ACCOUNT_CATEGORIES, newlyAddedRetiredCategories, RETIRED_ACCOUNT_CATEGORY_IDS, SELECTABLE_ACCOUNT_CATEGORY_IDS, createAccountRequestSchema, } from './accountGraph.js';
+export { usernameSchema, isValidUsername, stripDisallowedUsernameCharacters, USERNAME_MIN_LENGTH, USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE, } from './username.js';
 export { 
 // Schemas
 userNameSchema, userRelationshipSchema, themePreferenceSchema, userResponseSchema, userProfileUpdateSchema, currentUserResponseSchema, deviceLinkedSessionSchema, deviceLinkedSessionsResponseSchema, 

package/dist/esm/username.js

@@ -0,0 +1,163 @@
+/**
+ * Username policy — the ONE rule, for every kind of account.
+ *
+ * A username is a HANDLE: the routing key of a profile URL (`/@alice`), the
+ * local part of a webfinger `acct:`, and a login identifier. `users.username`
+ * carries a single unique index, `lower(btrim(username))`, and people, bots,
+ * organizations, projects and channels all draw from it. There is no per-kind
+ * namespace, so there is no per-kind rule — a bot that may reserve a name a
+ * person cannot ask for is a disagreement inside one index, not a variant.
+ *
+ * ## Why this file exists
+ *
+ * Seven rules governed this one namespace: four validators (this package's
+ * predecessor in `@oxyhq/api`, `@oxyhq/core`, `@oxyhq/commons`, and one written
+ * inline in `AccountService.resolveUniqueUsername`) and three that COERCED —
+ * silently deleting the characters they disliked, which hands somebody an
+ * account under a name they never chose. They lived in five packages and no test
+ * asserted they agreed. `contracts` is where the single declaration can actually
+ * live: `api`, `core`, `commons`, `services` and `auth` all already depend on it,
+ * so every write path can IMPORT the rule instead of restating it.
+ * `__tests__/usernamePolicySingleSource.test.ts` fails if a second one appears.
+ *
+ * ## The rule, and why each part of it
+ *
+ * ```
+ * 3–30 characters
+ * first and last character: [A-Za-z0-9]
+ * interior: [A-Za-z0-9_-]
+ * never two separators in a row
+ * ```
+ *
+ *  - **Hyphens are admitted because the DATABASE already admits them.**
+ *    `internal_cost_centers_slug_check` is a CHECK constraint —
+ *    `^[a-z0-9][a-z0-9-]{0,62}$` — and `seed-internal-cost-centers` mints a
+ *    `project` account whose username IS the slug; four of the five declared
+ *    centres contain a hyphen. An alphanumeric-only handle rule would contradict
+ *    a constraint written to permit them, and would make those centres
+ *    unmintable. This is the argument, not the four hyphenated accounts that
+ *    happen to exist — they are a symptom.
+ *  - **Dots are NOT admitted.** A dot is the delimiter that separates handle from
+ *    domain in the federated form this same column stores for remote actors
+ *    (`alice@mastodon.social`), it collides with extension-style routing
+ *    (`/@alice.json`), and `n.ate` beside `nate` is the strongest confusable pair
+ *    an ASCII handle can produce. Only the inline account rule ever accepted one,
+ *    and it accepted it by accident: its `[\w.-]` was written for a SLUG.
+ *  - **A length bound, always.** The account path had none — the only ceiling was
+ *    a `.max(100)` on the wire schema. 3 is the floor because `oxy`, the platform
+ *    owner's own organization, is three characters. 30 is the ceiling four of the
+ *    seven rules and the availability endpoint already published.
+ *  - **First and last character alphanumeric, and no `--` / `__` / `-_` run.**
+ *    Both are free — no account uses such a name — and they remove the
+ *    confusable shapes that admitting two separators would otherwise introduce.
+ *
+ * ## Case, and what this schema deliberately does not do
+ *
+ * **Case is PRESERVED.** Uniqueness is decided by the database's
+ * `lower(btrim(username))` index, so `Alice` and `alice` cannot coexist, but a
+ * name that was typed with a capital keeps it. This schema therefore never
+ * lower-cases: rewriting a caller's input is how `resolveUniqueUsername` used to
+ * return `mybot` to somebody who asked for `MyBot`.
+ *
+ * **This is a WRITE-path rule.** It states what may be newly stored, not what may
+ * be read. Rows that predate it — including 11 with no username at all — must go
+ * on loading, resolving and rendering; validating on a read turns an existing
+ * account into a 500.
+ *
+ * **It does not govern remote actors.** The same column holds ~73k federated
+ * rows in `handle@domain` form, written by `POST /users/resolve` through its own
+ * normalizer. Those are another server's namespace; this rule would reject every
+ * one of them and must never be pointed at that path.
+ *
+ * ## Usable by a handle GENERATOR, deliberately
+ *
+ * Slug generators are how the eighth copy of this rule appears. Alia's
+ * `suggestAgentUsername` builds one from an agent's name and re-derives a subset
+ * of these rules by hand — its own docblock admits it ("A leading digit or an
+ * empty slug both fail Oxy's username rules") — and, having no minimum, proposes
+ * `al` for an agent called "Al", which the server then refuses.
+ *
+ * So this module answers a generator's three questions without dragging a server
+ * dependency along. It is zod and nothing else, so it imports cleanly into a
+ * React Native bundle or another repo's backend:
+ *
+ *   - *Does this candidate pass?* {@link isValidUsername}, or `safeParse` when the
+ *     reason matters.
+ *   - *How short is too short, how long is too long?* {@link USERNAME_MIN_LENGTH}
+ *     and {@link USERNAME_MAX_LENGTH}, so a generator can pad or truncate instead
+ *     of guessing and being 400ed.
+ *   - *Which characters survive?* {@link stripDisallowedUsernameCharacters}.
+ *
+ * A generator PROPOSES; only `POST /accounts` decides, and a taken handle comes
+ * back as a 409 for the client to retry with a fresh suggestion. Nothing here
+ * 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';
+/**
+ * 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 one username policy, as a schema.
+ *
+ * `.trim()` first, so surrounding whitespace is a typo rather than a rejection —
+ * but interior whitespace is NOT removed. It falls to the pattern, because
+ * squashing `"al ice"` into `"alice"` would hand the user an account under a name
+ * they never chose. Every write path validates through THIS object; nothing
+ * re-implements it.
+ */
+export const usernameSchema = z
+    .string()
+    .trim()
+    .min(USERNAME_MIN_LENGTH, USERNAME_INVALID_MESSAGE)
+    .max(USERNAME_MAX_LENGTH, USERNAME_INVALID_MESSAGE)
+    .regex(USERNAME_PATTERN, USERNAME_INVALID_MESSAGE);
+/**
+ * Whether a candidate handle is storable — the boolean form, for input surfaces
+ * that show a message as somebody types rather than throwing.
+ *
+ * Answers from {@link usernameSchema}, so a client's inline check and the
+ * server's 400 cannot disagree.
+ */
+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, '');
+}