@antasphere/chassis-contract 0.0.0-stage → 1.0.0

package/src/schemas/api-keys.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+import type { ScopeSchema } from './scope.js';
+
+/** The API-key schemas carry the tool's scope vocabulary: built per tool (../define.ts). */
+export function defineApiKeySchemas<TScope extends string>(scopeSchema: ScopeSchema<TScope>) {
+  const apiKeySchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    keyId: z.string(),
+    scopes: z.array(scopeSchema),
+    /**
+     * The key's optional workspace PIN (user-scoped credential model). null =
+     * user-scoped: the key acts as its creator and the target workspace is a
+     * per-request parameter (X-Workspace-Id / the user's default). A value =
+     * the key reaches ONLY that workspace, forever.
+     */
+    workspaceId: z.string().nullable(),
+    createdBy: z.string(),
+    createdAt: z.string(),
+    lastUsedAt: z.string().nullable(),
+    revokedAt: z.string().nullable(),
+    expiresAt: z.string().nullable()
+  });
+
+  const apiKeysListSchema = z.object({
+    apiKeys: z.array(apiKeySchema),
+    nextCursor: z.string().nullable()
+  });
+
+  const apiKeyCreateSchema = z.object({
+    name: plainText(1, 120),
+    scopes: z.array(scopeSchema).min(1),
+    /** TTL at mint; the server computes the absolute expiry. Omit = never expires. */
+    expiresInDays: z.number().int().min(1).max(3650).optional(),
+    /**
+     * Optional workspace PIN (least privilege): the key then reaches ONLY this
+     * workspace — an ACTIVE membership of it is required at mint. Omit for a
+     * user-scoped key (the default): it acts as you in whichever of your
+     * workspaces each request names.
+     */
+    workspaceId: z.uuid().optional()
+  });
+
+  /** The secret appears exactly once, in this response. */
+  const apiKeyCreatedSchema = z.object({
+    apiKey: apiKeySchema,
+    /** Full key `<prefix>_<keyid>_<secret>` — shown once, never retrievable. */
+    key: z.string()
+  });
+
+  return { apiKeySchema, apiKeysListSchema, apiKeyCreateSchema, apiKeyCreatedSchema };
+}

package/src/schemas/audit.ts

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, noControlChars } from './common.js';
+
+export const auditEntrySchema = z.object({
+  id: z.number(),
+  actorUserId: z.string().nullable(),
+  actorEmail: z.string().nullable(),
+  actorVia: z.enum(['session', 'api_key', 'oauth', 'system']),
+  apiKeyId: z.string().nullable(),
+  action: z.string(),
+  resourceType: z.string(),
+  resourceId: z.string().nullable(),
+  requestId: z.string().nullable(),
+  ip: z.string().nullable(),
+  metadata: z.unknown().nullable(),
+  createdAt: z.string()
+});
+export type AuditEntry = z.infer<typeof auditEntrySchema>;
+
+export const auditViaSchema = z.enum(['session', 'api_key', 'oauth', 'system']);
+export type AuditVia = z.infer<typeof auditViaSchema>;
+
+/** The actor filter's reserved word: rows nobody signed (actor_user_id IS NULL). */
+export const AUDIT_ACTOR_SYSTEM = 'system';
+
+/**
+ * A comma-separated list of actions or families: an item ending in `.`
+ * matches the family (`apikey.` is every API key action), any
+ * other item matches exactly. The fallback action of an unlabelled route is
+ * `<method> <path>`, so a space and a slash are legitimate characters.
+ */
+const AUDIT_ACTION_LIST_RE = /^[a-z0-9_.\-/ ]+(,[a-z0-9_.\-/ ]+)*$/;
+const AUDIT_VIA_LIST_RE = /^(session|api_key|oauth|system)(,(session|api_key|oauth|system))*$/;
+
+/**
+ * The audit list's filters, every one optional and combined with AND. Each
+ * free-text one is bounded and control-char free: every value lands in a
+ * WHERE comparison, and a NUL there is a driver error (22021) that would
+ * surface as a 500 for a plain client mistake.
+ */
+export const auditListQuerySchema = cursorPageQuerySchema.extend({
+  /** Free text, matched case-insensitively against the actor's email and the action. */
+  q: noControlChars(z.string().max(120)).optional(),
+  /** Actions or families, comma-separated (`member.,apikey.create`); at most 20. */
+  action: z
+    .string()
+    .max(600)
+    .regex(AUDIT_ACTION_LIST_RE)
+    .refine((v) => v.split(',').length <= 20, { error: 'at most 20 actions' })
+    .optional(),
+  /** How the actor authenticated, comma-separated (`session,api_key`). */
+  actorVia: z.string().max(40).regex(AUDIT_VIA_LIST_RE).optional(),
+  /** One user id (a member of the workspace), or `system` for rows nobody signed. */
+  actor: noControlChars(z.string().min(1).max(64)).optional(),
+  resourceType: noControlChars(z.string().min(1).max(64)).optional(),
+  resourceId: noControlChars(z.string().min(1).max(200)).optional(),
+  /** Entries created at or after this instant (ISO 8601). */
+  from: z.iso.datetime().optional(),
+  /** Entries created at or before this instant (ISO 8601). */
+  to: z.iso.datetime().optional()
+});
+export type AuditListQuery = z.infer<typeof auditListQuerySchema>;
+
+export const auditListSchema = z.object({
+  entries: z.array(auditEntrySchema),
+  nextCursor: z.string().nullable(),
+  /**
+   * How many entries match the filters in all: counted on the first page
+   * only (no cursor), null on the pages after it. A client keeps the first
+   * page's figure while it loads more.
+   */
+  total: z.number().int().nullable()
+});
+export type AuditListResponse = z.infer<typeof auditListSchema>;

package/src/schemas/break-glass.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { workspaceRoleSchema } from './common.js';
+
+/**
+ * Break-glass superadmin recovery (ADR 010). Session-only endpoints gated by
+ * the SUPERADMIN_EMAILS env allowlist — deliberately unlisted in the machine
+ * scope allowlist, so API keys and OAuth tokens 403 fail-closed.
+ */
+
+/**
+ * Optional target user (omitted = the calling superadmin) and target
+ * workspace. `workspaceId` may be omitted ONLY while the instance runs a
+ * single workspace (every pre-ADR-012 deployment); a multi-workspace
+ * instance answers 400 workspace_required — recovery must name its target
+ * explicitly, never guess one.
+ */
+export const breakGlassClaimOwnershipRequestSchema = z.object({
+  userId: z.string().min(1).optional(),
+  workspaceId: z.uuid().optional()
+});
+export type BreakGlassClaimOwnershipRequest = z.infer<typeof breakGlassClaimOwnershipRequestSchema>;
+
+export const breakGlassClaimOwnershipSchema = z.object({
+  memberId: z.string(),
+  userId: z.string(),
+  email: z.string(),
+  /** The workspace the ownership was claimed in. */
+  workspaceId: z.string(),
+  role: workspaceRoleSchema,
+  isActive: z.boolean(),
+  /** true when the membership was created; false when an existing row was promoted/reactivated. */
+  created: z.boolean()
+});
+export type BreakGlassClaimOwnership = z.infer<typeof breakGlassClaimOwnershipSchema>;
+
+export const breakGlassResetTwoFactorRequestSchema = z.object({
+  userId: z.string().min(1)
+});
+export type BreakGlassResetTwoFactorRequest = z.infer<typeof breakGlassResetTwoFactorRequestSchema>;
+
+export const breakGlassResetTwoFactorSchema = z.object({
+  userId: z.string(),
+  /** true when a factor actually existed (row or enabled flag) before the reset. */
+  hadTwoFactor: z.boolean()
+});
+export type BreakGlassResetTwoFactor = z.infer<typeof breakGlassResetTwoFactorSchema>;

package/src/schemas/cli-auth.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+
+/**
+ * Browserless CLI/agent sign-in: email OTP → API key. Two PUBLIC (pre-auth)
+ * endpoints, mounted like /setup outside the principal machinery:
+ *
+ *   POST /cli/auth/request  — send a 6-digit sign-in code to the email
+ *   POST /cli/auth/complete — verify the code, mint an API key
+ *
+ * Sign-up stays CLOSED: the flow rides the emailOTP plugin with
+ * `disableSignUp: true`, so a code only ever signs in an EXISTING account
+ * (created via setup, a workspace invitation, or a collaborator claim).
+ * `request` answers a generic success for unknown emails (no enumeration);
+ * `complete` for an unknown email fails exactly like a wrong code. On the
+ * CLOUD edition both refuse (403 cli_otp_disabled) — hub-only login (D1).
+ *
+ * DELETE /cli/auth/key is the logout counterpart: it revokes exactly the
+ * PRESENTING API key (self-revocation — possession is the authority to kill
+ * itself), machine-allowed under the tool's write scope in the scope allowlist.
+ */
+
+export const cliAuthRequestSchema = z.object({
+  email: z.email()
+});
+export type CliAuthRequest = z.infer<typeof cliAuthRequestSchema>;
+
+/** Always `sent: true` on 2xx — deliberately silent about account existence. */
+export const cliAuthRequestedSchema = z.object({
+  sent: z.literal(true)
+});
+export type CliAuthRequested = z.infer<typeof cliAuthRequestedSchema>;
+
+export const cliAuthCompleteSchema = z.object({
+  email: z.email(),
+  otp: z.string().min(4).max(16),
+  /** Display name for the minted key (defaults to a CLI-login label). */
+  keyName: plainText(1, 120).optional(),
+  /** TTL at mint; the server computes the absolute expiry. Omit = never expires. */
+  expiresInDays: z.number().int().min(1).max(3650).optional(),
+  /**
+   * Optional workspace PIN (least privilege) — the account must hold an
+   * ACTIVE membership of it. Omit for a user-scoped key (the default): it
+   * acts as you in whichever of your workspaces each request names
+   * (X-Workspace-Id / your default membership).
+   */
+  workspaceId: z.uuid().optional()
+});
+export type CliAuthComplete = z.infer<typeof cliAuthCompleteSchema>;
+
+/** DELETE /cli/auth/key — the presenting key was revoked (CLI logout). */
+export const cliAuthRevokedSchema = z.object({
+  revoked: z.literal(true),
+  id: z.string()
+});
+export type CliAuthRevoked = z.infer<typeof cliAuthRevokedSchema>;
+
+/**
+ * The one CLI-auth schema that embeds the API key (and with it the tool's
+ * scope vocabulary): built per tool (../define.ts).
+ */
+export function defineCliAuthSchemas<TApiKey extends z.ZodType>(apiKeySchema: TApiKey) {
+  /** The full key appears exactly once, in this response (API-key semantics). */
+  const cliAuthCompletedSchema = z.object({
+    /** Full key `<prefix>_<keyid>_<secret>` — shown once, never retrievable. */
+    key: z.string(),
+    apiKey: apiKeySchema,
+    user: z.object({
+      id: z.string(),
+      email: z.string(),
+      name: z.string()
+    }),
+    /** The workspace the key is PINNED to; null = user-scoped (unpinned). */
+    workspaceId: z.string().nullable()
+  });
+
+  return { cliAuthCompletedSchema };
+}

package/src/schemas/common.ts

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+
+/**
+ * API conventions (fixed): plain resource JSON on success — no
+ * `{ success, data }` envelope; errors are `{ error: { code, message,
+ * details? } }`; cursor pagination.
+ */
+export const apiErrorSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.unknown().optional()
+  })
+});
+export type ApiError = z.infer<typeof apiErrorSchema>;
+
+export const workspaceRoleSchema = z.enum(['owner', 'admin', 'member']);
+export type WorkspaceRole = z.infer<typeof workspaceRoleSchema>;
+
+export const cursorPageQuerySchema = z.object({
+  cursor: z.string().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50)
+});
+/**
+ * Free text a client may send that ends up in a Postgres `text`/`varchar`
+ * column, a filename, or a log line.
+ *
+ * Postgres cannot store a NUL byte in a text value: it raises SQLSTATE 22021
+ * from deep inside the driver, which surfaces as an unhandled 500 whose
+ * error-level log line prints the failing statement AND its bound parameters.
+ * An anonymous client can drive that on any free-text sink (`/setup`, the
+ * invitation accept, the CLI key mint). NUL is never meaningful in a name, a
+ * label, or a title, so the contract refuses it and the caller gets the
+ * ordinary 400 validation_error instead.
+ *
+ * The other C0 controls are rejected with it: they are invisible in every UI,
+ * they are the raw material of log-injection and terminal-escape tricks, and
+ * no legitimate name contains one. Newlines and tabs are ALLOWED — multi-line
+ * free text is a real thing; a sink that must stay single-line adds its own
+ * `.regex()`.
+ */
+export function hasControlChars(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    // Tab / LF / CR are legitimate in multi-line free text.
+    if (code === 0x09 || code === 0x0a || code === 0x0d) continue;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+export function noControlChars<T extends z.ZodType<string>>(schema: T): T {
+  return schema.refine((v) => !hasControlChars(v), {
+    error: 'must not contain NUL or other control characters'
+  }) as unknown as T;
+}
+
+/**
+ * Postgres int4 ceiling. Every integer the API accepts that lands in an
+ * `integer` column (version numbers, cursors) must be bounded by it at the
+ * contract: `Number.isInteger(1e15)` is true, so a bare `.int()` lets a value
+ * past bigint-free column range through to Postgres, which refuses it with
+ * a numeric-overflow error that would surface as a 500.
+ */
+export const INT4_MAX = 2_147_483_647;
+
+/**
+ * True when the value graph carries a NUL character in any string — object
+ * keys included. Postgres cannot store NUL in `text` (SQLSTATE 22021) or in
+ * `jsonb` (`\u0000` raises 22P05), so any client-supplied structure bound for
+ * a jsonb column (annotation selections, form payloads, a resource's metadata) is
+ * refused at the contract instead of surfacing a driver error. Iterative walk
+ * — never recursion — so a deeply nested value cannot blow the stack in the
+ * very guard meant to protect against hostile shapes.
+ */
+export function hasNulDeep(value: unknown): boolean {
+  const stack: unknown[] = [value];
+  // A shared value graph (the contract is documented safe to run outside the
+  // server, where a caller may hand it a live object carrying a cycle) would
+  // spin this walk forever; the seen-set makes each container visited once.
+  const seen = new WeakSet<object>();
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (typeof current === 'string') {
+      if (current.includes('\u0000')) return true;
+    } else if (Array.isArray(current)) {
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const item of current) stack.push(item);
+    } else if (current !== null && typeof current === 'object') {
+      if (seen.has(current)) continue;
+      seen.add(current);
+      for (const [key, item] of Object.entries(current)) {
+        if (key.includes('\u0000')) return true;
+        stack.push(item);
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Nesting depth of a parsed JSON value, computed iteratively (the point is to
+ * measure hostile depth without recursing over it). Scalars are depth 0; an
+ * object or array adds one level. Contracts cap opaque structures with this
+ * BEFORE any `JSON.stringify` runs on them — stringify is recursive and blows
+ * the V8 stack with a RangeError at a build-dependent depth (SL-B5), so the
+ * check must come first, and the contract must stay safe even when consumed
+ * outside the server (SDK, dashboard) where no edge middleware ran.
+ */
+export function jsonDepthOf(value: unknown): number {
+  let max = 0;
+  const stack: Array<{ node: unknown; depth: number }> = [{ node: value, depth: 0 }];
+  // Same cycle guard as hasNulDeep: a live object with a back-reference must
+  // not make the depth walk (or the caller's later stringify) run forever.
+  const seen = new WeakSet<object>();
+  while (stack.length > 0) {
+    const { node, depth } = stack.pop()!;
+    if (depth > max) max = depth;
+    if (node !== null && typeof node === 'object') {
+      if (seen.has(node)) continue;
+      seen.add(node);
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) stack.push({ node: item, depth: depth + 1 });
+    } else if (node !== null && typeof node === 'object') {
+      for (const item of Object.values(node)) stack.push({ node: item, depth: depth + 1 });
+    }
+  }
+  return max;
+}
+
+/**
+ * Depth cap for the opaque JSON objects the contract carries (metadata,
+ * annotation selections, form payloads). Far above any legitimate shape —
+ * the deepest real structure is a handful of levels — and far below both the
+ * server edge cap (100) and the stringify breaking depth (~5000 on
+ * node:22-alpine).
+ */
+export const MAX_OPAQUE_JSON_DEPTH = 32;
+
+/**
+ * The shared guard for an opaque client-supplied JSON object bound for a
+ * jsonb column: depth-capped first (so the later size refine may stringify
+ * safely), then NUL-free. Compose it onto a `z.record(...)` with `.check`
+ * short-circuiting: zod runs refinements in order and skips later ones once
+ * one fails only when `abort` is set, so both checks abort.
+ */
+export function opaqueJsonChecks<T extends z.ZodType<Record<string, unknown>>>(schema: T): T {
+  return schema
+    .refine((v) => jsonDepthOf(v) <= MAX_OPAQUE_JSON_DEPTH, {
+      error: `must not nest deeper than ${MAX_OPAQUE_JSON_DEPTH} levels`,
+      abort: true
+    })
+    .refine((v) => !hasNulDeep(v), {
+      error: 'must not contain NUL characters in keys or values',
+      abort: true
+    }) as unknown as T;
+}
+
+/**
+ * The one free-text string builder: length-bounded and NUL-free.
+ * Every user-supplied name/label/title in this contract goes through it.
+ */
+export function plainText(min: number, max: number) {
+  return noControlChars(z.string().min(min).max(max));
+}
+
+/**
+ * RFC 7231 media type: `token "/" token`, optionally followed by
+ * `;`-separated `token=token|quoted-string` parameters. The manifest's
+ * `contentType` is copied VERBATIM into the response `Content-Type` header
+ * when the blob is served (`files/serve.ts`), including on the anonymous
+ * viewer — and versions are immutable, so a committed value that the
+ * `Headers` constructor refuses (a non-Latin-1 character, say) was a
+ * permanent anonymous 500 on that asset (PLT-5, PRDCT-1358). The grammar
+ * check at commit is the fix; the serve-time sanitizer is the backstop for
+ * rows committed before it.
+ */
+const MEDIA_TYPE_TOKEN = "[!#$%&'*+.^_`|~0-9A-Za-z-]+";
+export const MEDIA_TYPE_RE = new RegExp(
+  `^${MEDIA_TYPE_TOKEN}\\/${MEDIA_TYPE_TOKEN}` +
+    `(?:[ \\t]*;[ \\t]*${MEDIA_TYPE_TOKEN}=(?:${MEDIA_TYPE_TOKEN}|"[^"\\\\\\u0000-\\u001f\\u007f]*"))*$`
+);
+
+/**
+ * A response header VALUE is a ByteString: setting it converts each UTF-16
+ * code unit and throws a TypeError on any unit above 0xFF. The token grammar
+ * already excludes those in unquoted positions, but a quoted parameter value
+ * (`charset="€"`) can carry any character the regex's negated class does not
+ * name — U+20AC passes the pattern and then throws at the `Headers` set. So
+ * the Latin-1 ceiling is a SEPARATE, explicit check: every code unit ≤ 0xFF,
+ * which also rejects astral characters and lone surrogates (their code units
+ * are all ≥ 0xD800). Without it the grammar check is not the closure PLT-5
+ * needs.
+ */
+function isLatin1(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    if (value.charCodeAt(i) > 0xff) return false;
+  }
+  return true;
+}
+
+export function isValidMediaType(value: string): boolean {
+  return value.length >= 1 && value.length <= 255 && isLatin1(value) && MEDIA_TYPE_RE.test(value);
+}

package/src/schemas/demo-passes.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+
+/**
+ * A DEMO PASS is a link an owner mints so that one member of the workspace
+ * is signed in without a password, for a demonstration (the demo pass spec).
+ * The routes exist only while the instance's DEMO_SIGN_IN switch is on, on
+ * the self-hosted edition; `GET /instance` says so with `demoSignIn: true`.
+ * The secret is shown once, in the mint's answer, and stored nowhere.
+ */
+
+/** A pass's lifetime when the mint names none: one day, in minutes. */
+export const DEMO_PASS_DEFAULT_MINUTES = 1440;
+/** The longest lifetime a mint may ask for: one week, in minutes. */
+export const DEMO_PASS_MAX_MINUTES = 10080;
+
+export const demoPassSchema = z.object({
+  id: z.string(),
+  /** The person the pass signs in. */
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  /** The page the link lands on. */
+  targetPath: z.string(),
+  /** The owner who minted it; null once that account is gone. */
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  expiresAt: z.string(),
+  revokedAt: z.string().nullable(),
+  lastUsedAt: z.string().nullable(),
+  /** How many sessions the pass has opened. */
+  useCount: z.number().int()
+});
+export type DemoPass = z.infer<typeof demoPassSchema>;
+
+export const demoPassesListSchema = z.object({ passes: z.array(demoPassSchema) });
+export type DemoPassesList = z.infer<typeof demoPassesListSchema>;
+
+/**
+ * The mint: a member of the caller's workspace by address, the page the link
+ * lands on (a same-origin path, checked by the server), and a lifetime.
+ */
+export const demoPassMintSchema = z.object({
+  email: z.email(),
+  path: z.string().optional(),
+  expiresInMinutes: z.number().int().min(1).max(DEMO_PASS_MAX_MINUTES).optional()
+});
+export type DemoPassMint = z.infer<typeof demoPassMintSchema>;
+
+export const demoPassMintedSchema = z.object({
+  pass: demoPassSchema,
+  /** The secret itself: shown here once, never again. */
+  secret: z.string(),
+  /** `<PUBLIC_BASE_URL>/demo#pass=<secret>&to=<path>`: the fragment never reaches a server log. */
+  url: z.string()
+});
+export type DemoPassMinted = z.infer<typeof demoPassMintedSchema>;
+
+/**
+ * `POST /api/v1/auth/demo/redeem`: served by the sign-in library itself (so
+ * its own cookie and hooks apply), hence no route contract; these two
+ * shapes are the wire the SDK's `redeemDemoPass` speaks.
+ */
+export const demoPassRedeemSchema = z.object({ pass: z.string().min(1) });
+export type DemoPassRedeem = z.infer<typeof demoPassRedeemSchema>;
+
+export const demoPassRedeemedSchema = z.object({
+  user: z.object({ id: z.string(), email: z.string(), name: z.string() }),
+  /** The pass's page: where the dashboard goes when the link names none. */
+  path: z.string(),
+  /** When the PASS expires (the session it opened keeps its own lifetime). */
+  expiresAt: z.string()
+});
+export type DemoPassRedeemed = z.infer<typeof demoPassRedeemedSchema>;

package/src/schemas/files.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+
+export const fileSchema = z.object({
+  id: z.string(),
+  sha256: z.string(),
+  sizeBytes: z.number(),
+  contentType: z.string(),
+  originalName: z.string(),
+  /** Null once the uploader's account was deleted (files are workspace data). */
+  createdBy: z.string().nullable(),
+  createdAt: z.string()
+});
+export type FileInfo = z.infer<typeof fileSchema>;
+
+export const filesListSchema = z.object({
+  files: z.array(fileSchema),
+  nextCursor: z.string().nullable()
+});
+
+export const fileUploadedSchema = z.object({
+  file: fileSchema,
+  /** True when identical bytes already existed for this workspace. */
+  deduplicated: z.boolean()
+});
+
+export const fileUploadQuerySchema = z.object({
+  /** Original filename (the body is the raw bytes). */
+  name: plainText(1, 255)
+});

package/src/schemas/instance.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { KNOWN_AUTH_METHODS } from '../seams.js';
+import { toolEntitlementsSchema } from '../entitlements.js';
+
+/**
+ * GET /api/v1/instance — unauthenticated, cacheable discovery. This is what
+ * CLIs and MCP clients read to route: which auth methods exist, whether
+ * first-boot setup is still pending, and what the instance is.
+ */
+export const instanceInfoSchema = z.object({
+  name: z.string(),
+  instanceId: z.string().nullable(),
+  edition: z.string(),
+  version: z.string(),
+  apiVersion: z.literal('v1'),
+  setupRequired: z.boolean(),
+  auth: z.object({
+    // Open enum (ADR 003): the enum documents the known vocabulary, the
+    // string branch keeps older clients parsing newer instances. Clients
+    // ignore entries they do not recognize.
+    methods: z.array(z.enum(KNOWN_AUTH_METHODS).or(z.string())),
+    passwordReset: z.boolean(),
+    emailChange: z.boolean(),
+    twoFactor: z.boolean(),
+    /**
+     * Hub SSO client hints (cloud edition ONLY — absent on oss, where the
+     * discovery wire shape stays byte-identical). The hint cookie is a
+     * dashboard-side HINT for the silent auto-connect (attempt vs don't),
+     * NEVER a security input: the hub sets it, this tool reads it
+     * client-side and clears it on logout / login_required
+     * (internal/federation.md, cross-repo contract).
+     */
+    sso: z
+      .object({
+        hintCookieName: z.string(),
+        hintCookieDomain: z.string()
+      })
+      .optional()
+  }),
+  features: z.object({
+    mcp: z.boolean(),
+    oauth: z.boolean(),
+    files: z.boolean()
+  }),
+  /**
+   * `true` while the operator's DEMO_SIGN_IN switch is on (self-hosted
+   * edition only): demo links sign people in here, and the dashboard shows
+   * every signed-in person a banner saying so. ABSENT otherwise, never false,
+   * so an instance without the switch serves the same discovery bytes as
+   * before it existed.
+   */
+  demoSignIn: z.boolean().optional(),
+  /**
+   * `true` when this cloud instance is a RESTRICTED tool (the operator's
+   * TOOL_RESTRICTED switch, PRDCT-2947): organizations that open it are
+   * granted by Antasphere, and `POST /workspaces` refuses here. A CLI reads
+   * it to say so before offering to create one. ABSENT otherwise, never
+   * false, so the self-hosted discovery bytes are unchanged.
+   */
+  restricted: z.boolean().optional(),
+  /**
+   * What this version of the tool declares for the billing rail (its priced
+   * actions with their default credits, its limits and features per tier):
+   * the hub seeds its price book and its plan entitlements from it, staff
+   * read what a version declares, and a client reads the limit it will be
+   * held to (the CLI's upfront refusal with the right number). Optional on
+   * the wire so a client keeps parsing an instance from before the rail.
+   */
+  entitlements: toolEntitlementsSchema.optional()
+});
+export type InstanceInfo = z.infer<typeof instanceInfoSchema>;