@antasphere/chassis-contract 0.0.0-stage → 1.0.1

package/src/schemas/teams.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, noControlChars, plainText, workspaceRoleSchema } from './common.js';
+
+/**
+ * Teams: named groups of the workspace's people, on BOTH editions with the
+ * same routes and screens; only the source differs (PRDCT-2813). On the
+ * self-hosted edition, and in a cloud-local workspace, owners and admins
+ * make and shape them here; in a hub-origin workspace they are the hub's
+ * projection, read here and managed on the account site (every write answers
+ * `hub_managed`). Every non-guest member reads the teams and a team's
+ * members. A team holds the workspace's MEMBERSHIPS, so it can never hold an
+ * outsider, and a person leaves every team with their membership.
+ *
+ * The shapes mirror the hub's own teams contract (its `schemas/teams.ts`), so
+ * the two Teams pages read the same; a person is named by their user id or
+ * their email, as on this tool's project routes.
+ */
+
+/** A team's slug: lowercase words joined by single dashes, unique within a workspace. */
+export const teamSlugSchema = z
+  .string()
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'lowercase letters and digits, joined by single dashes')
+  .min(1)
+  .max(60);
+
+export const teamSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  membersCount: z.number().int(),
+  /** The caller belongs to this team. */
+  isMember: z.boolean(),
+  /**
+   * The hub's team id when the team is the account site's projection (the
+   * Manage link opens it there); null for a team the tool owns.
+   */
+  hubTeamId: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+export type Team = z.infer<typeof teamSchema>;
+
+export const teamsListSchema = z.object({
+  teams: z.array(teamSchema),
+  nextCursor: z.string().nullable()
+});
+export type TeamsList = z.infer<typeof teamsListSchema>;
+
+export const teamsListQuerySchema = cursorPageQuerySchema;
+
+export const teamCreateSchema = z.object({
+  name: plainText(1, 80),
+  /** Absent: derived from the name (lowercased, non-alphanumerics to dashes, cut to 60). */
+  slug: teamSlugSchema.optional()
+});
+export type TeamCreate = z.infer<typeof teamCreateSchema>;
+
+export const teamUpdateSchema = z
+  .object({
+    name: plainText(1, 80).optional(),
+    slug: teamSlugSchema.optional()
+  })
+  .refine((b) => b.name !== undefined || b.slug !== undefined, { error: 'nothing to change' });
+export type TeamUpdate = z.infer<typeof teamUpdateSchema>;
+
+export const teamMemberSchema = z.object({
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  /** The person's role in the WORKSPACE (a team has no roles of its own). */
+  role: workspaceRoleSchema,
+  isActive: z.boolean(),
+  addedAt: z.string()
+});
+export type TeamMemberInfo = z.infer<typeof teamMemberSchema>;
+
+export const teamMembersListSchema = z.object({
+  members: z.array(teamMemberSchema),
+  nextCursor: z.string().nullable()
+});
+export type TeamMembersList = z.infer<typeof teamMembersListSchema>;
+
+/**
+ * Seat one of the workspace's OWN active non-guest members, named by user id
+ * or by email: exactly one of the two. Nothing is invited or minted here.
+ */
+export const teamMemberAddSchema = z
+  .object({
+    userId: plainText(1, 200).optional(),
+    email: z.email().optional()
+  })
+  .refine((v) => (v.userId === undefined) !== (v.email === undefined), {
+    error: 'exactly one of userId or email is required'
+  });
+export type TeamMemberAdd = z.infer<typeof teamMemberAddSchema>;
+
+/** `{id}` the team (a uuid); `{userId}` Better Auth's text id: bounded free text, no control characters. */
+export const teamMemberParamsSchema = z.object({
+  id: z.uuid(),
+  userId: noControlChars(z.string().min(1).max(200))
+});

package/src/schemas/workspaces.ts

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+
+/**
+ * A workspace's look: one of the dashboard's theme keys and one pattern key
+ * of the brand's library. A fact of the WORKSPACE (every member sees the
+ * same tile), kept as two short slugs the server does not interpret: the
+ * dashboard owns the catalogue and falls back to its defaults on a key it
+ * does not know, so retiring a theme never breaks a workspace. null = the
+ * dashboard's default for this workspace.
+ */
+const lookKey = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{0,31}$/, 'a short lowercase key')
+  .nullable();
+/**
+ * How much of the field's gradient reaches the page, and how much grain sits
+ * on it: 0..1, the workspace's too (they were each browser's until
+ * 2026-09-19, so two members never saw the same page). null = the brand's
+ * constant.
+ */
+const lookLevel = z.number().min(0).max(1).nullable();
+export const workspaceLookSchema = z.object({
+  theme: lookKey,
+  pattern: lookKey,
+  field: lookLevel,
+  grain: lookLevel
+});
+export type WorkspaceLook = z.infer<typeof workspaceLookSchema>;
+
+/**
+ * POST /api/v1/workspaces — a signed-in person creates ANOTHER workspace from
+ * inside the product (PRDCT-2444 self-hosted, PRDCT-2443 cloud). One route,
+ * one body, one answer on both editions; the dashboard keys off
+ * `/me.canCreateWorkspace` and never sniffs the edition.
+ *
+ *  - Self-hosted: the workspace is created locally with the caller as its
+ *    active owner, under the operator's per-person cap
+ *    (`MAX_WORKSPACES_PER_USER`).
+ *  - Cloud: the organization is created at Antasphere AS THE CALLER, then
+ *    projected locally before the answer — `workspace.id` is always the
+ *    LOCAL workspace id, the one `X-Workspace-Id` selects.
+ *
+ * Sessions only: API keys and OAuth bearers are refused (the route is
+ * deliberately absent from the machine scope allowlist). The name is trimmed
+ * server-side; a name that is blank once trimmed answers 400. The look the
+ * person picked in the dialog rides along, so the workspace is born with it
+ * on every member's screen.
+ */
+export const workspaceCreateSchema = z.object({
+  name: plainText(1, 120),
+  look: workspaceLookSchema.partial().optional()
+});
+export type WorkspaceCreate = z.infer<typeof workspaceCreateSchema>;
+
+export const workspaceCreatedSchema = z.object({
+  workspace: z.object({
+    /** The LOCAL workspace id — pass it as `X-Workspace-Id` to work in it. */
+    id: z.string(),
+    name: z.string(),
+    look: workspaceLookSchema
+  })
+});
+export type WorkspaceCreated = z.infer<typeof workspaceCreatedSchema>;
+
+/**
+ * PUT /api/v1/me/default-workspace — the workspace a request naming none
+ * resolves to, chosen by the person for themselves (PRDCT-2815). `null`
+ * clears the choice: the oldest active membership answers again. On the
+ * cloud edition the default is a setting of the person's Antasphere account,
+ * projected here at every sign-in: the route answers 403 `hub_managed` with
+ * the account site to set it on.
+ */
+export const defaultWorkspaceSetSchema = z.object({
+  workspaceId: z.string().uuid().nullable()
+});
+export type DefaultWorkspaceSet = z.infer<typeof defaultWorkspaceSetSchema>;
+
+export const defaultWorkspaceSchema = z.object({
+  /** The LOCAL id of the person's default workspace, or null when none is chosen. */
+  defaultWorkspaceId: z.string().nullable()
+});
+export type DefaultWorkspace = z.infer<typeof defaultWorkspaceSchema>;
+
+/**
+ * PATCH /api/v1/workspace — the ACTIVE workspace's own settings (its name,
+ * its look), by an owner or an admin of it, from a browser session. The
+ * route names no id: a request works in exactly one workspace (ADR 014),
+ * and that is the one it edits. On the cloud edition a hub-origin
+ * workspace's NAME is the hub's (P7): a rename answers 403 `hub_managed`
+ * with the console to do it at; its look stays a local fact and is
+ * accepted.
+ */
+export const workspaceUpdateSchema = z
+  .object({
+    name: plainText(1, 120).optional(),
+    look: workspaceLookSchema.partial().optional()
+  })
+  .refine((b) => b.name !== undefined || b.look !== undefined, { message: 'nothing to change' });
+export type WorkspaceUpdate = z.infer<typeof workspaceUpdateSchema>;
+
+export const workspaceUpdatedSchema = z.object({
+  workspace: z.object({
+    id: z.string(),
+    name: z.string(),
+    look: workspaceLookSchema
+  })
+});
+export type WorkspaceUpdated = z.infer<typeof workspaceUpdatedSchema>;

package/src/seams.ts

@@ -0,0 +1,202 @@
+/**
+ * The central-rail seam: three small interfaces wired through the boot-time
+ * module registry. The central account/credits service is NOT part of the
+ * template — these interfaces are the socket it plugs into later with zero
+ * refactor. Template defaults: LocalIdentityProvider, AllowAllEntitlements,
+ * a no-op UsageSink.
+ */
+
+/** Structural Headers so the contract stays lib-agnostic (works in DOM and Node). */
+export interface HeaderReader {
+  get(name: string): string | null;
+}
+
+export interface RequestContext {
+  /** Raw request headers (credential material lives here). */
+  headers: HeaderReader;
+  path: string;
+  method: string;
+  requestId: string;
+}
+
+/**
+ * The universal per-request workspace selector (user-scoped credential
+ * model). EVERY credential kind — session, API key, OAuth bearer — MAY send
+ * it to name which of the caller's workspaces this request targets; the
+ * resolvers verify an ACTIVE membership of that workspace and resolve to
+ * null otherwise (fail closed — no oracle about the workspace's existence).
+ * Absent, the user's DEFAULT membership is used, else the deterministic
+ * fallback (oldest active membership). The one exception is a PINNED API
+ * key (an optional least-privilege pin, and the grandfathered binding of
+ * keys minted under the old per-workspace model): it always resolves its
+ * pinned workspace, and a header naming a DIFFERENT one is rejected
+ * outright (403 workspace_mismatch).
+ */
+export const ACTIVE_WORKSPACE_HEADER = 'x-workspace-id';
+
+/**
+ * The resolved caller of ONE request. A credential identifies a USER; the
+ * Principal is still scoped to exactly ONE workspace per request (ADR 014):
+ * `workspaceId` is the workspace this request SELECTED via
+ * {@link ACTIVE_WORKSPACE_HEADER} (or the user's default), authorized
+ * against the caller's own live memberships. A user's OTHER memberships are
+ * deliberately not represented here; a request never spans workspaces.
+ */
+export interface Principal {
+  userId: string;
+  email: string;
+  name: string;
+  workspaceId: string;
+  role: 'owner' | 'admin' | 'member';
+  /**
+   * How the resolved membership came to exist (D2, internal/federation.md §P6):
+   * 'local' = ordinary membership (setup, workspace invitation), 'hub' = a
+   * hub-org projection (cloud SSO), 'guest' = an external per-resource
+   * collaborator minted by the claim path. Origin is a CAPABILITY axis, not
+   * a role: a guest resolves like any member but is refused resource creation
+   * and workspace-level surfaces (requireNonGuest) on BOTH editions — their
+   * access is the per-resource grant (ADR 013), which stays untouched. Every
+   * credential path (session, API key, OAuth bearer) reads it live from the
+   * membership row backing the request's workspace.
+   */
+  origin: 'local' | 'hub' | 'guest';
+  via: 'session' | 'api_key' | 'oauth';
+  /** Scope allowlist for machine principals; null = full role-based (session). */
+  scopes: ReadonlySet<string> | null;
+  apiKeyId?: string;
+  /** Expiry of the presented API key (ISO 8601) — absent for non-expiring keys. */
+  apiKeyExpiresAt?: string;
+  /** Central account id — undefined in local mode. */
+  accountRef?: string;
+  /**
+   * The credential itself fixed the workspace (an API key pinned to one):
+   * the request's selector was checked against the pin, and no default of
+   * the person ever moves the request elsewhere. Absent on every credential
+   * whose workspace the request selected, or the person's default chose.
+   */
+  pinned?: true;
+}
+
+/**
+ * Sign-in methods an instance can advertise in discovery. The set is OPEN
+ * (ADR 003 reserved this): clients must IGNORE entries they do not
+ * recognize, so an edition can add a method — like the cloud edition's
+ * 'antasphere' hub SSO — without breaking older SDKs/CLIs. This list is the
+ * known vocabulary, not a closed enum.
+ */
+export const KNOWN_AUTH_METHODS = [
+  'password',
+  'email-otp',
+  'google',
+  'api-key',
+  'oauth',
+  'antasphere'
+] as const;
+export type KnownAuthMethod = (typeof KNOWN_AUTH_METHODS)[number];
+
+export interface InstanceAuthDescriptor {
+  /** Open set — known values in {@link KNOWN_AUTH_METHODS}; ignore unknown entries. */
+  methods: Array<KnownAuthMethod | (string & {})>;
+  /** Self-serve password reset is available (requires a configured email driver). */
+  passwordReset: boolean;
+  /** Self-serve email change is available (requires a configured email driver). */
+  emailChange: boolean;
+  /** Opt-in per-user 2FA (TOTP + backup codes) is available on this instance. */
+  twoFactor: boolean;
+}
+
+export interface IdentityProvider {
+  /** Resolve a request to a live principal (fresh membership check) or null. */
+  resolve(ctx: RequestContext): Promise<Principal | null>;
+  /** Feeds the instance discovery endpoint. */
+  describe(): InstanceAuthDescriptor;
+}
+
+export interface MeteredAction {
+  /** The action key, e.g. 'files.upload' (the route's `meter.key`, namespaced by the tool's price book). */
+  key: string;
+  quantity: number;
+  unit: string;
+}
+
+export type EntitlementDecision = { allowed: true } | { allowed: false; reason: string };
+
+/** Per-principal general-API request quota, enforced by the server's quota middleware. */
+export interface RequestQuota {
+  /** Sustained allowance per principal per minute. 0 = unlimited (the limiter is skipped). */
+  perMinute: number;
+  /** Spike cap per principal per second inside the minute window. 0 = no burst smoothing. */
+  burstPerSecond: number;
+}
+
+export interface EntitlementService {
+  check(
+    principal: Principal,
+    action: MeteredAction,
+    ctx?: Record<string, unknown>
+  ): Promise<EntitlementDecision>;
+  /**
+   * Request-rate quota for this principal. The template default returns the
+   * instance-level env caps for everyone; a plan-aware edition varies it per
+   * account/plan. The quota is enforced per authenticated principal identity
+   * (API key id / OAuth subject / session user id), never per client header.
+   */
+  getRequestQuota(principal: Principal): Promise<RequestQuota>;
+}
+
+/**
+ * One metered action, as the tool emits it and the hub ingests it (the
+ * billing rail spec, §5 `POST /usage/events`). At-least-once from the tool;
+ * exactly-once at the hub by `id`. Paid by the account, reported per user.
+ */
+export interface UsageEvent {
+  /** ULID — the idempotency key; receivers dedupe on it (at-least-once emission). */
+  id: string;
+  /** The action key (`meter` is its historical name; the two carry the same value). */
+  meter: string;
+  actionKey: string;
+  quantity: number;
+  unit: string;
+  occurredAt: string; // ISO 8601
+  workspaceId: string;
+  /** The paying account (the workspace's central account id). */
+  accountRef?: string;
+  /** The reported user; null when the actor is a resource owner the tool could not name. */
+  userId: string | null;
+  /** How the action arrived: a session (the dashboard), an API key (the CLI), an OAuth client (an MCP connector). */
+  via: 'session' | 'api_key' | 'oauth';
+  /** The resource the handler recorded (its audit `resourceType` / `resourceId`), when it recorded one. */
+  resourceType?: string;
+  resourceId?: string;
+  source: {
+    instanceId: string;
+    edition: string;
+    version: string;
+  };
+}
+
+export interface UsageSink {
+  emit(event: UsageEvent): Promise<void>;
+}
+
+/**
+ * What a downstream says about a batch it took: the events it did NOT post
+ * because the hub would refuse them on their date (PRDCT-2644), each with
+ * its reason. The worker sends those to the held queue instead of leaving
+ * them counted as rejections at the hub; an empty list, or no outcome at
+ * all, means the whole batch was handled.
+ */
+export interface UsageBatchOutcome {
+  held: ReadonlyArray<{ id: string; reason: string }>;
+}
+
+/**
+ * Where the durable queue hands the events it drained: the no-op locally,
+ * the hub poster on cloud. A downstream that takes whole batches gets them
+ * as the worker drained them (fifty at most); one that only takes single
+ * events is called once per event. A batch downstream may answer an outcome
+ * naming the events it held back.
+ */
+export interface UsageDownstream extends UsageSink {
+  emitBatch?(events: readonly UsageEvent[]): Promise<void | UsageBatchOutcome>;
+}

package/test/define.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { defineChassisContract, type ApiKeyInfoOf, type MeResponseOf, type ScopeOf } from '../src/index.js';
+import { defineChassisRoutes } from '../src/routes/index.js';
+
+/**
+ * The factory is the one place the chassis meets a tool's scope vocabulary.
+ * Proven here with scopes that are NOT any real tool's, so the chassis stays
+ * honest about never spelling one.
+ */
+const a = defineChassisContract({ scopes: ['widgets:read', 'widgets:write'] });
+const b = defineChassisContract({ scopes: ['gadgets:admin'] });
+
+describe('defineChassisContract', () => {
+  it('builds the scope enum from the scopes it is given, in order', () => {
+    expect(a.scopeSchema.options).toEqual(['widgets:read', 'widgets:write']);
+    expect(b.scopeSchema.options).toEqual(['gadgets:admin']);
+  });
+
+  it('types Scope as the union of the literals passed in', () => {
+    expectTypeOf<ScopeOf<typeof a>>().toEqualTypeOf<'widgets:read' | 'widgets:write'>();
+    expectTypeOf<ApiKeyInfoOf<typeof a>['scopes']>().toEqualTypeOf<Array<'widgets:read' | 'widgets:write'>>();
+    expectTypeOf<MeResponseOf<typeof b>['scopes']>().toEqualTypeOf<Array<'gadgets:admin'> | null>();
+  });
+
+  it('threads the enum into every schema that carries scopes', () => {
+    expect(a.apiKeyCreateSchema.safeParse({ name: 'k', scopes: ['widgets:read'] }).success).toBe(true);
+    expect(a.apiKeyCreateSchema.safeParse({ name: 'k', scopes: ['gadgets:admin'] }).success).toBe(false);
+    expect(b.apiKeyCreateSchema.safeParse({ name: 'k', scopes: ['gadgets:admin'] }).success).toBe(true);
+    expect(a.cliAuthCompletedSchema.shape.apiKey).toBe(a.apiKeySchema);
+    expect(a.meResponseSchema.shape.scopes.unwrap().element).toBe(a.scopeSchema);
+  });
+
+  it('holds no module-level state: two instantiations never share a schema', () => {
+    expect(a.scopeSchema).not.toBe(b.scopeSchema);
+    expect(a.apiKeySchema).not.toBe(b.apiKeySchema);
+    expect(a.meResponseSchema).not.toBe(b.meResponseSchema);
+  });
+});
+
+describe('defineChassisRoutes', () => {
+  it('returns the eight route contracts over the instantiated schemas', () => {
+    const routes = defineChassisRoutes(
+      a,
+      { cliKeyScopesLabel: 'widgets:read+write', scopes: { dataExport: 'widgets:export' } },
+      { fileInUseOpenApi: 'file_in_use: referenced by a widget' }
+    );
+    expect(Object.entries(routes).map(([name, r]) => `${name} ${r.method} ${r.path}`)).toEqual([
+      'meRoute get /me',
+      'apiKeysListRoute get /api-keys',
+      'apiKeyCreateRoute post /api-keys',
+      'apiKeyRevokeRoute delete /api-keys/{id}',
+      'cliAuthCompleteRoute post /cli/auth/complete',
+      'ssoCliConnectRoute post /sso/cli-connect',
+      'workspaceExportRoute get /workspace/export',
+      'fileDeleteRoute delete /files/{id}'
+    ]);
+    expect(routes.meRoute.responses[200].content['application/json'].schema).toBe(a.meResponseSchema);
+  });
+});

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.