@antasphere/chassis-contract 0.0.0-stage → 1.0.0

package/src/schemas/invitations.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { plainText, workspaceRoleSchema } from './common.js';
+
+export const invitationSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  role: workspaceRoleSchema,
+  invitedBy: z.string(),
+  expiresAt: z.string(),
+  acceptedAt: z.string().nullable(),
+  revokedAt: z.string().nullable(),
+  createdAt: z.string()
+});
+export type InvitationInfo = z.infer<typeof invitationSchema>;
+
+export const invitationsListSchema = z.object({
+  invitations: z.array(invitationSchema),
+  nextCursor: z.string().nullable()
+});
+
+export const invitationCreateSchema = z.object({
+  email: z.email(),
+  role: workspaceRoleSchema.default('member')
+});
+export type InvitationCreate = z.infer<typeof invitationCreateSchema>;
+
+/**
+ * The copyable acceptance link is ALWAYS returned — SMTP is never required
+ * to get a teammate in. `emailSent` says whether a mail also went out.
+ */
+export const invitationCreatedSchema = z.object({
+  invitation: invitationSchema,
+  acceptUrl: z.string(),
+  emailSent: z.boolean()
+});
+export type InvitationCreated = z.infer<typeof invitationCreatedSchema>;
+
+/**
+ * Deliberately carries NO account-existence signal (the collaborator-lookup
+ * rule, PRDCT-1437): an admin who creates an invitation naming any address
+ * holds the copyable accept URL, so the lookup was an instance-global
+ * account oracle. The accept page offers sign-in and create-account
+ * neutrally; the accept endpoint answers `account_exists` when a create
+ * collides.
+ */
+export const invitationLookupSchema = z.object({
+  email: z.string(),
+  role: workspaceRoleSchema,
+  workspaceName: z.string(),
+  expiresAt: z.string()
+});
+export type InvitationLookup = z.infer<typeof invitationLookupSchema>;
+
+export const invitationAcceptSchema = z.object({
+  token: z.string().min(16),
+  /** Required when the invited email has no account yet. */
+  name: plainText(1, 120).optional(),
+  password: z.string().min(12).max(256).optional()
+});
+export type InvitationAccept = z.infer<typeof invitationAcceptSchema>;
+
+export const invitationAcceptedSchema = z.object({
+  workspaceId: z.string(),
+  userId: z.string(),
+  role: workspaceRoleSchema
+});

package/src/schemas/me.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { workspaceRoleSchema } from './common.js';
+import type { ScopeSchema } from './scope.js';
+import { workspaceLookSchema } from './workspaces.js';
+
+/**
+ * POST /api/v1/me/onboarding/dismiss (cloud edition ONLY; sessions only —
+ * machines 403 fail-closed via the scope allowlist, oss answers the JSON
+ * 404 terminator): records the explicit dismissal that flips
+ * `firstRunPending` to false, permanently (upsert; an earlier dismissal
+ * timestamp is preserved). Idempotent — dismissing twice is a no-op.
+ */
+export const onboardingDismissedSchema = z.object({
+  dismissed: z.literal(true)
+});
+export type OnboardingDismissed = z.infer<typeof onboardingDismissedSchema>;
+
+/** `/me` reports the credential's scopes, so it is built per tool (../define.ts). */
+export function defineMeSchemas<TScope extends string>(scopeSchema: ScopeSchema<TScope>) {
+  /**
+   * GET /api/v1/me — the resolved AuthContext of the calling principal,
+   * whichever credential path it arrived on. The whoami for humans, keys, and
+   * (later) OAuth tokens alike; also the MCP get_me tool's backing endpoint.
+   *
+   * ZERO-MEMBERSHIP sessions answer 200 too (user-scoped federation): a LIVE
+   * session whose user holds no active membership — the cloud operator before
+   * break-glass, a hub user whose last org was removed — gets
+   * `{ workspaces: [], workspace: null, activeWorkspaceId: null, role: null,
+   * origin: null, via: 'session' }` instead of a 401, so the dashboard can
+   * render the no-organization zero state instead of a login bounce. Machine
+   * credentials never see this shape: a key/token whose user has no active
+   * membership fails resolution (401) before the route runs.
+   */
+  const meResponseSchema = z.object({
+    user: z.object({
+      id: z.string(),
+      email: z.string(),
+      name: z.string()
+    }),
+    /**
+     * The ACTIVE workspace this request resolved to (= activeWorkspaceId).
+     * Null ONLY for the zero-membership session state described above.
+     */
+    workspace: z
+      .object({
+        id: z.string(),
+        name: z.string(),
+        /**
+         * True when this workspace is the lazy projection of a hub org (cloud
+         * edition, internal/federation.md) — its MEMBERSHIP is managed at the hub,
+         * so clients hide local member/invitation management and link out
+         * (P7). Derived from `centralAccountId IS NOT NULL`; the raw hub org
+         * id is deliberately never exposed. Always false on oss.
+         */
+        hubOrigin: z.boolean(),
+        /** The workspace's look, a fact of the workspace (schemas/workspaces.ts). */
+        look: workspaceLookSchema
+      })
+      .nullable(),
+    /** Null only in the zero-membership session state. */
+    role: workspaceRoleSchema.nullable(),
+    /**
+     * How the caller's membership of the ACTIVE workspace came to exist
+     * (mirrors Principal.origin): 'local' = setup/invitation, 'hub' = SSO
+     * projection (cloud), 'guest' = a per-resource collaborator (D2) — clients
+     * hide the guest-forbidden workspace surfaces (resource creation, files,
+     * member roster, export) for 'guest'. Null only in the zero-membership
+     * session state.
+     */
+    origin: z.enum(['local', 'hub', 'guest']).nullable(),
+    via: z.enum(['session', 'api_key', 'oauth']),
+    scopes: z.array(scopeSchema).nullable(),
+    /** Expiry of the presented API key; null for sessions/OAuth or non-expiring keys. */
+    apiKeyExpiresAt: z.string().nullable(),
+    /**
+     * The workspaces this credential can name (user-scoped credential model):
+     * EVERY credential kind — session, API key, OAuth bearer — lists ALL of
+     * the user's active memberships; the target workspace is a per-request
+     * parameter (X-Workspace-Id), never baked into the credential. Clients
+     * MUST read the `default` flag to find the selector-less default — never
+     * assume index 0.
+     */
+    workspaces: z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        role: workspaceRoleSchema,
+        /** Same semantics as `workspace.hubOrigin`, per listed workspace. */
+        hubOrigin: z.boolean(),
+        /**
+         * The id of the hub organization this workspace projects (cloud
+         * edition), null on a local workspace and always on self-hosted. It
+         * is the person's own organization id, the one the account site
+         * shows them, and it is what `--org <hub org id or name>` resolves
+         * against: a request may name a workspace by this id in
+         * X-Workspace-Id as well as by `id` (PRDCT-2947).
+         */
+        centralAccountId: z.string().nullable(),
+        /** Each workspace's look, so the switcher's tiles carry them (schemas/workspaces.ts). */
+        look: workspaceLookSchema,
+        /**
+         * The hub asserted this org suspended (cloud edition): it stays
+         * VISIBLE here but requests into it are refused. Always false on oss
+         * and on local workspaces.
+         */
+        suspended: z.boolean(),
+        /**
+         * The user's default workspace — what a request naming no workspace
+         * resolves to. At most one entry carries it; when none does, the
+         * deterministic fallback (oldest active membership) applies.
+         */
+        default: z.boolean()
+      })
+    ),
+    /**
+     * The workspace THIS request resolved to — what X-Workspace-Id selects.
+     * Null only in the zero-membership session state.
+     */
+    activeWorkspaceId: z.string().nullable(),
+    /**
+     * Where membership of the ACTIVE workspace is managed when it is
+     * hub-origin (the hub account console, e.g. https://account.antasphere.com)
+     * — the dashboard's link-out target (P7). Also set for the CLOUD
+     * zero-membership session state (the "create an organization at
+     * Antasphere" CTA target). null on oss and on local (non-projected)
+     * workspaces.
+     */
+    hubManageUrl: z.string().nullable(),
+    /**
+     * Whether `POST /workspaces` would be accepted for this caller RIGHT NOW
+     * (PRDCT-2444 / PRDCT-2443) — the one flag the dashboard keys its "new
+     * workspace" entry off, on both editions, never the edition itself. True
+     * only for a SESSION whose user is not guest-only, while the operator's
+     * `MAX_WORKSPACES_PER_USER` dial is not 0; on self-hosted the user must
+     * also own fewer workspaces than that cap, on cloud they must also hold a
+     * live Antasphere link (the organization is created there, as them).
+     * Always false for API keys and OAuth bearers. STAYS TRUE on cloud for a
+     * person whose stored sign-in predates workspace creation (the route then
+     * answers 401 `hub_reauth_required`): the creation is one sign-in away,
+     * and false would hide the entry from them for good. Advisory: the route
+     * re-judges everything, and on cloud the hub's own cap is only known once
+     * asked.
+     */
+    canCreateWorkspace: z.boolean(),
+    /**
+     * First-run welcome still owed (SL-6). CLOUD + SESSION callers ONLY —
+     * absent on oss and for every machine credential. TOOL-LOCAL and
+     * retry-safe semantics: true iff NO user_onboarding row with a dismissal
+     * exists (`NOT EXISTS (row WHERE dismissed_at IS NOT NULL)`), so a lost
+     * first-login write still shows the welcome and only an explicit
+     * POST /me/onboarding/dismiss (or the deploy backfill) ever hides it.
+     * The hub's advisory `tool_first_login` claim plays no part.
+     */
+    firstRunPending: z.boolean().optional(),
+    /**
+     * The hint-watch discriminator (SL-4/SL-6). CLOUD + SESSION callers ONLY
+     * — absent on oss and for machine credentials. True iff the user's ONLY
+     * way in is hub SSO: they hold an `antasphere` account row AND no local
+     * credential (password) account row. A break-glass-capable operator has
+     * a credential account and is therefore NEVER ssoOnly — the dashboard's
+     * hint-watch may auto-sign-out ssoOnly users when the hub hint cookie
+     * disappears, and must never sign out an operator.
+     */
+    ssoOnly: z.boolean().optional(),
+    /**
+     * The organizations the person belongs to at Antasphere that do NOT open
+     * this tool to them (the organization lets only some of its teams use
+     * it). CLOUD + SESSION callers only; absent on the self-hosted edition
+     * and for machine credentials, and a reader treats an absent field as
+     * none (an older server never sends it). A hint for the refusal page,
+     * read from the hub's last answer as the person: the hub is the truth,
+     * never this list.
+     */
+    hubDenied: z.array(z.object({ id: z.string(), name: z.string() })).optional(),
+    /**
+     * The Antasphere page that lists whom to ask for this tool (the owners
+     * and admins of the refusing organization), ready-made with the tool's
+     * client id. CLOUD + SESSION callers only; absent otherwise.
+     */
+    hubNoAccessUrl: z.string().optional()
+  });
+
+  return { meResponseSchema };
+}

package/src/schemas/members.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { workspaceRoleSchema } from './common.js';
+
+export const memberSchema = z.object({
+  id: z.string(),
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  role: workspaceRoleSchema,
+  isActive: z.boolean(),
+  createdAt: z.string(),
+  lastSeenAt: z.string().nullable()
+});
+export type Member = z.infer<typeof memberSchema>;
+
+export const membersListSchema = z.object({
+  members: z.array(memberSchema),
+  nextCursor: z.string().nullable()
+});
+
+// Both fields optional, so an empty body must be refused HERE: `{}` used to
+// pass validation and build an empty drizzle `.set({})`, which Postgres
+// refuses — an anonymous-shaped 500 for a plain client mistake (FUZZ-5,
+// PRDCT-1358).
+export const memberUpdateSchema = z
+  .object({
+    role: workspaceRoleSchema.optional(),
+    isActive: z.boolean().optional()
+  })
+  .refine((v) => v.role !== undefined || v.isActive !== undefined, {
+    error: 'at least one of role or isActive is required'
+  });
+export type MemberUpdate = z.infer<typeof memberUpdateSchema>;
+
+/** Admin-generated password reset link for a member (the SMTP-free recovery path). */
+export const memberResetLinkSchema = z.object({
+  resetUrl: z.string(),
+  expiresAt: z.string()
+});
+export type MemberResetLink = z.infer<typeof memberResetLinkSchema>;
+
+/** Admin-generated email change link for a member (the SMTP-free email-change path). */
+export const memberChangeEmailLinkRequestSchema = z.object({
+  newEmail: z.email()
+});
+export type MemberChangeEmailLinkRequest = z.infer<typeof memberChangeEmailLinkRequestSchema>;
+
+export const memberChangeEmailLinkSchema = z.object({
+  verifyUrl: z.string(),
+  newEmail: z.string(),
+  expiresAt: z.string()
+});
+export type MemberChangeEmailLink = z.infer<typeof memberChangeEmailLinkSchema>;

package/src/schemas/projects.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+import { cursorPageQuerySchema, noControlChars, opaqueJsonChecks, plainText } from './common.js';
+
+/**
+ * A PROJECT is a subgroup of a workspace: a name, a description, members with
+ * a role, and the tool's resources linked to it. The chassis owns the
+ * concept; what a project HOLDS is the tool's (its own link table, its own
+ * routes). A project is archived, never deleted.
+ */
+
+/**
+ * The three project roles, each one containing the one before it:
+ *  - `viewer`: reads the project and what is linked to it;
+ *  - `editor`: viewer + writes what is linked to it, links resources of their own;
+ *  - `manager`: editor + edits the project, archives it, manages its members.
+ * A workspace owner or admin acts as a manager on every project.
+ */
+export const projectRoleSchema = z.enum(['manager', 'editor', 'viewer']);
+export type ProjectRole = z.infer<typeof projectRoleSchema>;
+
+const PROJECT_ROLE_RANK: Record<ProjectRole, number> = { viewer: 0, editor: 1, manager: 2 };
+
+/** True when `role` is `min` or contains it (`manager` ≥ `editor` ≥ `viewer`). */
+export function projectRoleAtLeast(role: ProjectRole, min: ProjectRole): boolean {
+  return PROJECT_ROLE_RANK[role] >= PROJECT_ROLE_RANK[min];
+}
+
+/**
+ * Serialized size cap for a project's owner-defined metadata object, in
+ * JSON.stringify characters (an environment-free proxy for bytes: the
+ * contract runs in browsers and Node alike).
+ */
+export const PROJECT_METADATA_MAX_LENGTH = 16 * 1024;
+
+/**
+ * Owner-defined structured metadata: a plain JSON object, opaque to the
+ * server beyond shape and size. This is the tool's and the integrator's seam,
+ * the reason no tool ever needs a column on the project. PATCH replaces the
+ * whole object; merge is a client concern.
+ */
+export const projectMetadataSchema = opaqueJsonChecks(z.record(z.string(), z.unknown())).refine(
+  (v) => JSON.stringify(v).length <= PROJECT_METADATA_MAX_LENGTH,
+  `metadata must serialize to at most ${PROJECT_METADATA_MAX_LENGTH} characters`
+);
+
+export const projectSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string().nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  /** Set while the project is archived: out of the default list, read-only. */
+  archivedAt: z.string().nullable(),
+  createdBy: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  /** The CALLER's effective role (`manager` for a workspace owner or admin). */
+  myRole: projectRoleSchema,
+  memberCount: z.number().int()
+});
+export type Project = z.infer<typeof projectSchema>;
+
+export const projectsListSchema = z.object({
+  projects: z.array(projectSchema),
+  nextCursor: z.string().nullable()
+});
+export type ProjectsList = z.infer<typeof projectsListSchema>;
+
+/** `false` (the default) = the live projects, `true` = the archived ones, `all` = both. */
+export const projectsArchivedFilterSchema = z.enum(['false', 'true', 'all']);
+export type ProjectsArchivedFilter = z.infer<typeof projectsArchivedFilterSchema>;
+
+export const projectsListQuerySchema = cursorPageQuerySchema.extend({
+  archived: projectsArchivedFilterSchema.default('false')
+});
+
+export const projectCreateSchema = z.object({
+  name: plainText(1, 200),
+  description: plainText(0, 2000).optional(),
+  metadata: projectMetadataSchema.optional()
+});
+export type ProjectCreate = z.infer<typeof projectCreateSchema>;
+
+// Every field optional, so an empty body is refused HERE (an empty drizzle
+// `.set({})` is a Postgres error, not a client mistake answered 400).
+export const projectUpdateSchema = z
+  .object({
+    name: plainText(1, 200).optional(),
+    /** `null` clears the description. */
+    description: plainText(0, 2000).nullable().optional(),
+    metadata: projectMetadataSchema.optional()
+  })
+  .refine((v) => v.name !== undefined || v.description !== undefined || v.metadata !== undefined, {
+    error: 'at least one of name, description or metadata is required'
+  });
+export type ProjectUpdate = z.infer<typeof projectUpdateSchema>;
+
+/**
+ * A project's members are people AND teams, each with a role (PRDCT-2794):
+ * one list, told apart by `kind`. A team entry's role is what every active
+ * non-guest member of the team holds through it; a person's effective role
+ * is the highest of their own entry and their teams' entries. `kind` is
+ * `person` on every entry that predates teams, so a reader that never asked
+ * for teams still reads what it did.
+ */
+export const projectPersonMemberSchema = z.object({
+  kind: z.literal('person'),
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  role: projectRoleSchema,
+  addedBy: z.string().nullable(),
+  createdAt: z.string()
+});
+export type ProjectPersonMember = z.infer<typeof projectPersonMemberSchema>;
+
+export const projectTeamMemberSchema = z.object({
+  kind: z.literal('team'),
+  teamId: z.string(),
+  slug: z.string(),
+  name: z.string(),
+  /**
+   * How many seats the team holds here, the account site's count. A
+   * deactivated member keeps their seat (a pause) and holds nothing through
+   * it until reactivated; the team's page shows each seat's state.
+   */
+  membersCount: z.number().int(),
+  /** The hub's team id when the team is the account site's projection; null for the tool's own. */
+  hubTeamId: z.string().nullable(),
+  role: projectRoleSchema,
+  addedBy: z.string().nullable(),
+  createdAt: z.string()
+});
+export type ProjectTeamMember = z.infer<typeof projectTeamMemberSchema>;
+
+export const projectMemberSchema = z.discriminatedUnion('kind', [
+  projectPersonMemberSchema,
+  projectTeamMemberSchema
+]);
+export type ProjectMember = z.infer<typeof projectMemberSchema>;
+
+export const projectMembersListSchema = z.object({
+  members: z.array(projectMemberSchema),
+  nextCursor: z.string().nullable()
+});
+export type ProjectMembersList = z.infer<typeof projectMembersListSchema>;
+
+/**
+ * Add one of the workspace's OWN active members, named by user id or by
+ * email, or one of the workspace's teams by its id: exactly one of the three.
+ * No invitation, no claim token, no account is ever minted here.
+ */
+export const projectMemberAddSchema = z
+  .object({
+    userId: plainText(1, 200).optional(),
+    email: z.email().optional(),
+    teamId: z.uuid().optional(),
+    role: projectRoleSchema
+  })
+  .refine((v) => [v.userId, v.email, v.teamId].filter((k) => k !== undefined).length === 1, {
+    error: 'exactly one of userId, email or teamId is required'
+  });
+export type ProjectMemberAdd = z.infer<typeof projectMemberAddSchema>;
+
+export const projectMemberRoleSchema = z.object({ role: projectRoleSchema });
+export type ProjectMemberRoleUpdate = z.infer<typeof projectMemberRoleSchema>;
+
+/** A user id is Better Auth's text id, never a uuid: bounded free text, no control characters. */
+export const projectMemberParamsSchema = z.object({
+  id: z.uuid(),
+  userId: noControlChars(z.string().min(1).max(200))
+});
+
+/** `{id}` the project and `{teamId}` the team, both uuids. */
+export const projectTeamParamsSchema = z.object({ id: z.uuid(), teamId: z.uuid() });

package/src/schemas/scope.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+
+/**
+ * The scope vocabulary is the TOOL's identity (`products:read`, …), so the
+ * chassis never spells one: a tool hands its scopes to
+ * `defineChassisContract({ scopes })` (../define.ts) and gets back the enum
+ * and every schema that carries it.
+ */
+export type ScopeTuple = readonly [string, ...string[]];
+
+/** The zod enum over a tool's scopes — exactly what `z.enum([...scopes])` builds. */
+export type ScopeSchema<TScope extends string> = z.ZodEnum<{ [K in TScope]: K }>;
+
+export function defineScopeSchema<const TScopes extends ScopeTuple>(
+  scopes: TScopes
+): ScopeSchema<TScopes[number]> {
+  return z.enum(scopes) as unknown as ScopeSchema<TScopes[number]>;
+}

package/src/schemas/setup.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { plainText } from './common.js';
+
+/**
+ * POST /api/v1/setup — one-shot first-boot wizard: creates the owner user
+ * and, on the OSS edition, the instance's FIRST workspace (later ones come
+ * from `POST /workspaces`). Guarded by the
+ * singleton instance_settings row (second attempt → 410) and, optionally, a
+ * SETUP_TOKEN. On the CLOUD edition setup creates NO workspace (the
+ * response's `workspaceId` is null): every cloud workspace is a hub-org
+ * projection, so the operator bootstrap mints a verified, break-glass
+ * capable USER only (internal/federation.md, user-scoped federation).
+ */
+export const setupRequestSchema = z.object({
+  instanceName: plainText(1, 120),
+  owner: z.object({
+    email: z.email(),
+    name: plainText(1, 120),
+    password: z.string().min(12).max(256)
+  }),
+  setupToken: z.string().optional()
+});
+export type SetupRequest = z.infer<typeof setupRequestSchema>;
+
+export const setupResponseSchema = z.object({
+  instanceId: z.string(),
+  /** The first workspace (oss); null on cloud — no workspace is created there. */
+  workspaceId: z.string().nullable(),
+  ownerUserId: z.string()
+});
+export type SetupResponse = z.infer<typeof setupResponseSchema>;

package/src/schemas/sso-connect.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+
+/**
+ * CLI cross-tool connect (cloud edition only — internal/federation.md P5):
+ *
+ *   POST /sso/cli-connect — exchange a hub-minted 120 s JWT for an API key
+ *
+ * The counterpart of the hub's H3 `POST /sso/tool-token`: `antasphere login`
+ * mints a hub API key once; the hub exchanges it for a short-lived RS256 JWT
+ * (`aud` = THIS instance's resource URL, `purpose: 'sso-connect'`, unique
+ * `jti`) PLUS a one-time raw offline-grant refresh token (`hubRefreshToken`,
+ * scopes `offline_access account:read` — the HUB mints it, so it carries no
+ * `orgs:create`: a CLI connect REPLACES the stored grant, and the person's
+ * next workspace creation answers `hub_reauth_required` until they sign in
+ * with the browser again), and this endpoint turns the pair
+ * into an ordinary USER-scoped local API key — no tool-specific login, and
+ * the stored grant drives the same live as-the-user hub org reads as a
+ * browser SSO login's. PUBLIC path (the hub JWT IS the credential),
+ * rate-limited, jti one-time-use. Registered ONLY on EDITION=cloud; an oss
+ * instance answers 404 (the route does not exist there).
+ *
+ * The response reuses the CLI-auth completion shape (`CliAuthCompleted`) —
+ * the tool's read + write scopes, never its export scope, full key
+ * shown exactly once; `workspaceId` is null (user-scoped, unpinned).
+ */
+
+export const ssoCliConnectSchema = z.object({
+  /** The hub-minted exchange JWT (compact JWS — three base64url segments). */
+  token: z.string().min(20).max(4096),
+  /**
+   * The raw one-time offline-grant refresh token from the SAME H3 response
+   * (`hubRefreshToken`). Stored encrypted on the account row — it is what
+   * keeps a headless CLI user's org reads LIVE between browser logins.
+   * Optional on the wire for older clients, but a connect that carries none
+   * is refused unless a prior grant already exists (a key must never be
+   * minted born-dead).
+   */
+  hubRefreshToken: z.string().min(20).max(512).optional()
+});
+export type SsoCliConnect = z.infer<typeof ssoCliConnectSchema>;

package/src/schemas/sso-logout.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+
+/**
+ * POST /api/v1/sso/logout (cloud edition ONLY — oss answers the JSON 404
+ * terminator): the single-logout server leg. The server has ALREADY revoked
+ * the local session and cleared the shared hint cookie by the time this
+ * body arrives; `url` is the hub RP-initiated-logout URL the browser must
+ * now VISIT to end the hub anchor session (it lands back on
+ * `/login?signed_out=1`). `null` = no hub leg was possible (no stored
+ * id_token, a pre-flip sid-less one, hub unreachable) — the client goes to
+ * `/login?signed_out=1` directly; the LOCAL signout already happened either
+ * way.
+ */
+export const ssoLogoutResponseSchema = z.object({
+  url: z.string().nullable()
+});
+export type SsoLogoutResponse = z.infer<typeof ssoLogoutResponseSchema>;