@smartcrab/contracts-management 0.1.0

package/src/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @smartcrab/contracts-management — zod request/response contracts for
+ * the Management API (design.md §26), consumed by control-worker routes,
+ * `@smartcrab/management-client`, the dashboard SPA, and the CLI.
+ *
+ * Mirrors `@smartcrab/contracts-public`'s conventions: a local
+ * dependency-free style (no `@smartcrab/result`), `idPattern`-based id
+ * schemas, `z.strictObject` on every response shape, and per-field doc
+ * comments citing design.md sections.
+ */
+export * from "./common.js";
+export * from "./primitives.js";
+export * from "./rbac.js";
+export * from "./api-keys.js";
+export * from "./workspaces.js";
+export * from "./projects.js";
+export * from "./environments.js";
+export * from "./clients.js";
+export * from "./connections.js";
+export * from "./domains.js";
+export * from "./users.js";
+export * from "./user-subresources.js";
+export * from "./user-jobs.js";
+export * from "./webhooks.js";
+export * from "./audit-events.js";
+export * from "./usage.js";
+export * from "./billing.js";

package/src/primitives.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+
+/**
+ * Shared primitives for the Management API (design.md §26).
+ *
+ * ID schemas for kinds already modeled by `@smartcrab/contracts-public`
+ * (client/user/session/passkey/identity/webhook) are re-exported from there
+ * rather than redefined, per the assignment notes: this package's
+ * `package.json` only declares `zod` and `@smartcrab/contracts-public` as
+ * dependencies, so `@smartcrab/identifiers` and `@smartcrab/tenant-context`
+ * are not resolvable here directly (pnpm's strict `node_modules` only links a
+ * package's own declared dependencies, not its transitive ones). For the
+ * remaining ID kinds this Management API surface needs
+ * (workspace/project/environment/connection/domain/job/management-api-key/
+ * audit-event) that `contracts-public` does not export, the exact
+ * `<prefix>_<32 base32url chars>` rule and prefix table are mirrored locally
+ * from `@smartcrab/identifiers`'s `ID_PREFIXES` (design.md §7.5) so the
+ * pattern never drifts from the canonical source.
+ */
+export {
+  clientIdSchema,
+  httpsUrlSchema,
+  identityIdSchema,
+  isoDateTimeSchema,
+  passkeyIdSchema,
+  sessionIdSchema,
+  userIdSchema,
+  webhookIdSchema,
+} from "@smartcrab/contracts-public";
+export type {
+  ClientId,
+  IdentityId,
+  PasskeyId,
+  SessionId,
+  UserId,
+  WebhookId,
+} from "@smartcrab/contracts-public";
+
+/** Mirrors `@smartcrab/identifiers`'s `ID_PREFIXES` (design.md §7.5) for kinds not re-exported above. */
+const LOCAL_ID_PREFIXES = {
+  workspace: "wsp",
+  project: "prj",
+  environment: "env",
+  connection: "con",
+  domain: "dom",
+  job: "job",
+  apiKey: "mky",
+  event: "evt",
+  delivery: "dlv",
+} as const;
+
+type LocalIdKind = keyof typeof LOCAL_ID_PREFIXES;
+
+/** Zod-ready regex, identical shape to `@smartcrab/identifiers`'s `idPattern`. */
+const localIdPattern = (kind: LocalIdKind): RegExp =>
+  new RegExp(`^${LOCAL_ID_PREFIXES[kind]}_[a-z2-7]{32}$`);
+
+export const workspaceIdSchema = z.string().regex(localIdPattern("workspace"));
+export type WorkspaceId = z.infer<typeof workspaceIdSchema>;
+
+export const projectIdSchema = z.string().regex(localIdPattern("project"));
+export type ProjectId = z.infer<typeof projectIdSchema>;
+
+export const environmentIdSchema = z.string().regex(localIdPattern("environment"));
+export type EnvironmentId = z.infer<typeof environmentIdSchema>;
+
+export const connectionIdSchema = z.string().regex(localIdPattern("connection"));
+export type ConnectionId = z.infer<typeof connectionIdSchema>;
+
+export const domainIdSchema = z.string().regex(localIdPattern("domain"));
+export type DomainId = z.infer<typeof domainIdSchema>;
+
+export const jobIdSchema = z.string().regex(localIdPattern("job"));
+export type JobId = z.infer<typeof jobIdSchema>;
+
+export const apiKeyIdSchema = z.string().regex(localIdPattern("apiKey"));
+export type ApiKeyId = z.infer<typeof apiKeyIdSchema>;
+
+export const auditEventIdSchema = z.string().regex(localIdPattern("event"));
+export type AuditEventId = z.infer<typeof auditEventIdSchema>;
+
+/**
+ * Generic domain event ID (`evt_...`, design.md §7.5) — the exact same ID
+ * kind as `auditEventIdSchema` above, exported under a resource-neutral name
+ * for consumers (e.g. `webhooks.ts`'s delivery history `event_id`) that
+ * reference a domain event without being about the audit log itself.
+ */
+export const eventIdSchema = z.string().regex(localIdPattern("event"));
+export type EventId = z.infer<typeof eventIdSchema>;
+
+/** `webhook_delivery_history.id` (design.md §29.4, §10.10): `dlv_...`. */
+export const deliveryIdSchema = z.string().regex(localIdPattern("delivery"));
+export type DeliveryId = z.infer<typeof deliveryIdSchema>;
+
+/** `workspaces.slug` / `projects.slug` (design.md §11.1, §11.3): URL-safe, lowercase, hyphenated. */
+export const slugSchema = z
+  .string()
+  .min(1)
+  .max(63)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);

package/src/projects.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "vitest";
+import { projectCreateRequestSchema, projectListQuerySchema, projectSchema } from "./projects.js";
+
+const VALID_PROJECT = {
+  id: `prj_${"a".repeat(32)}`,
+  workspace_id: `wsp_${"a".repeat(32)}`,
+  name: "Storefront",
+  slug: "storefront",
+  created_at: "2026-08-02T08:10:00Z",
+  updated_at: "2026-08-02T08:10:00Z",
+  deleted_at: null,
+};
+
+describe("projectSchema (design.md §11.3)", () => {
+  test("accepts a valid project", () => {
+    expect(projectSchema.safeParse(VALID_PROJECT).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key", () => {
+    expect(projectSchema.safeParse({ ...VALID_PROJECT, internal_note: "x" }).success).toBe(false);
+  });
+
+  test("rejects a malformed id", () => {
+    expect(projectSchema.safeParse({ ...VALID_PROJECT, id: "not-a-project-id" }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("projectCreateRequestSchema", () => {
+  test("requires workspace_id and name; slug is optional", () => {
+    expect(
+      projectCreateRequestSchema.safeParse({
+        workspace_id: VALID_PROJECT.workspace_id,
+        name: "Storefront",
+      }).success,
+    ).toBe(true);
+    expect(projectCreateRequestSchema.safeParse({ name: "Storefront" }).success).toBe(false);
+  });
+});
+
+describe("projectListQuerySchema (pagination, design.md §26.3)", () => {
+  test("rejects a page size above the max of 100", () => {
+    expect(
+      projectListQuerySchema.safeParse({ workspace_id: VALID_PROJECT.workspace_id, limit: 250 })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/projects.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { projectIdSchema, slugSchema, workspaceIdSchema } from "./primitives.js";
+
+/** `projects` (design.md §11.3, §7.2). No secret/internal-routing columns. */
+export const projectSchema = z.strictObject({
+  id: projectIdSchema,
+  workspace_id: workspaceIdSchema,
+  name: z.string().min(1).max(200),
+  slug: slugSchema,
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+  deleted_at: z.iso.datetime().nullable(),
+});
+export type Project = z.infer<typeof projectSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /projects
+// ---------------------------------------------------------------------------
+
+/** `/projects` is a flat top-level route (design.md §26.2); `workspace_id` scopes the listing. */
+export const projectListQuerySchema = paginationQuerySchema.extend({
+  workspace_id: workspaceIdSchema,
+});
+export type ProjectListQuery = z.infer<typeof projectListQuerySchema>;
+
+export const projectListResponseSchema = cursorPageSchema(projectSchema);
+export type ProjectListResponse = z.infer<typeof projectListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /projects
+// ---------------------------------------------------------------------------
+
+export const projectCreateRequestSchema = z.strictObject({
+  workspace_id: workspaceIdSchema,
+  name: z.string().min(1).max(200),
+  slug: slugSchema.optional(),
+});
+export type ProjectCreateRequest = z.infer<typeof projectCreateRequestSchema>;
+
+export const projectCreateResponseSchema = projectSchema;
+export type ProjectCreateResponse = z.infer<typeof projectCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /projects/:projectId
+// ---------------------------------------------------------------------------
+
+export const projectGetResponseSchema = projectSchema;
+export type ProjectGetResponse = z.infer<typeof projectGetResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /projects/:projectId
+// ---------------------------------------------------------------------------
+
+export const projectUpdateRequestSchema = z.strictObject({
+  name: z.string().min(1).max(200).optional(),
+  slug: slugSchema.optional(),
+});
+export type ProjectUpdateRequest = z.infer<typeof projectUpdateRequestSchema>;
+
+export const projectUpdateResponseSchema = projectSchema;
+export type ProjectUpdateResponse = z.infer<typeof projectUpdateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// DELETE /projects/:projectId (design.md §11.3 `deleted_at` — logical delete)
+// ---------------------------------------------------------------------------
+
+export const projectDeleteResponseSchema = z.strictObject({
+  id: projectIdSchema,
+  deleted: z.literal(true),
+});
+export type ProjectDeleteResponse = z.infer<typeof projectDeleteResponseSchema>;

package/src/rbac.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "vitest";
+import {
+  CREDENTIAL_MUTATING_SCOPES,
+  IMPERSONATION_MAX_DURATION_MINUTES,
+  MANAGEMENT_SCOPES,
+  ROLE_SCOPES,
+  WORKSPACE_ROLES,
+  impersonationCreateRequestSchema,
+  isReadOnlyScope,
+  roleHasScope,
+  scopesForRole,
+  workspaceRoleSchema,
+} from "./rbac.js";
+
+const USER_ID = `usr_${"a".repeat(32)}`;
+
+describe("WORKSPACE_ROLES (design.md §27.2 / §11.2)", () => {
+  test("matches the exact six roles from the design", () => {
+    expect(WORKSPACE_ROLES).toEqual([
+      "owner",
+      "admin",
+      "developer",
+      "support",
+      "billing",
+      "viewer",
+    ]);
+  });
+
+  test("workspaceRoleSchema rejects an unknown role", () => {
+    expect(workspaceRoleSchema.safeParse("superadmin").success).toBe(false);
+  });
+});
+
+describe("scopesForRole / roleHasScope", () => {
+  test("scopesForRole returns exactly ROLE_SCOPES[role]", () => {
+    for (const role of WORKSPACE_ROLES) {
+      expect(scopesForRole(role)).toBe(ROLE_SCOPES[role]);
+    }
+  });
+
+  test("roleHasScope reflects membership in ROLE_SCOPES", () => {
+    expect(roleHasScope("owner", "billing:write")).toBe(true);
+    expect(roleHasScope("viewer", "billing:write")).toBe(false);
+    expect(roleHasScope("viewer", "billing:read")).toBe(true);
+  });
+});
+
+describe("design.md §27.2 role table invariants", () => {
+  test("owner's scopes are a superset of every other role's scopes", () => {
+    const ownerScopes = new Set(ROLE_SCOPES.owner);
+    for (const role of WORKSPACE_ROLES) {
+      if (role === "owner") continue;
+      for (const scope of ROLE_SCOPES[role]) {
+        expect(ownerScopes.has(scope)).toBe(true);
+      }
+    }
+  });
+
+  test("owner is granted every scope that exists", () => {
+    expect(new Set(ROLE_SCOPES.owner)).toEqual(new Set(MANAGEMENT_SCOPES));
+  });
+
+  test("viewer is read-only: every one of its scopes is a `:read` scope", () => {
+    expect(ROLE_SCOPES.viewer.length).toBeGreaterThan(0);
+    for (const scope of ROLE_SCOPES.viewer) {
+      expect(isReadOnlyScope(scope)).toBe(true);
+    }
+  });
+
+  test("support lacks every credential-mutating scope (design.md §25)", () => {
+    for (const scope of CREDENTIAL_MUTATING_SCOPES) {
+      expect(ROLE_SCOPES.support.includes(scope)).toBe(false);
+    }
+    // §27.2: support's only write capability is session revocation.
+    expect(roleHasScope("support", "user_sessions:write")).toBe(true);
+    expect(roleHasScope("support", "users:write")).toBe(false);
+    expect(roleHasScope("support", "users:block")).toBe(false);
+    expect(roleHasScope("support", "users:delete")).toBe(false);
+  });
+
+  test("developer has integration resource scopes and token introspection (design.md §27.2)", () => {
+    const allowedResources = ["clients", "connections", "domains", "webhooks"];
+    expect(ROLE_SCOPES.developer.length).toBeGreaterThan(0);
+    expect(ROLE_SCOPES.developer).toContain("introspect");
+    for (const scope of ROLE_SCOPES.developer) {
+      if (scope === "introspect") continue;
+      const resource = scope.split(":")[0] ?? "";
+      expect(allowedResources).toContain(resource);
+    }
+  });
+
+  test("introspect is a read-only scope for owner/admin/developer", () => {
+    expect(MANAGEMENT_SCOPES).toContain("introspect");
+    expect(isReadOnlyScope("introspect")).toBe(true);
+    for (const role of ["owner", "admin", "developer"] as const) {
+      expect(roleHasScope(role, "introspect")).toBe(true);
+    }
+    for (const role of ["support", "billing", "viewer"] as const) {
+      expect(roleHasScope(role, "introspect")).toBe(false);
+    }
+  });
+
+  test("workspace_members:read is granted to owner/admin/support/billing/viewer but withheld from developer", () => {
+    expect(roleHasScope("owner", "workspace_members:read")).toBe(true);
+    expect(roleHasScope("admin", "workspace_members:read")).toBe(true);
+    expect(roleHasScope("support", "workspace_members:read")).toBe(true);
+    expect(roleHasScope("billing", "workspace_members:read")).toBe(true);
+    expect(roleHasScope("viewer", "workspace_members:read")).toBe(true);
+    expect(roleHasScope("developer", "workspace_members:read")).toBe(false);
+  });
+});
+
+describe("impersonation (design.md §27.4)", () => {
+  const base = { user_id: USER_ID, reason: "Investigating a customer-reported login bug." };
+
+  test("accepts a valid request within the 15-minute cap", () => {
+    expect(
+      impersonationCreateRequestSchema.safeParse({
+        ...base,
+        duration_minutes: IMPERSONATION_MAX_DURATION_MINUTES,
+      }).success,
+    ).toBe(true);
+  });
+
+  test("rejects a duration over 15 minutes", () => {
+    expect(
+      impersonationCreateRequestSchema.safeParse({
+        ...base,
+        duration_minutes: IMPERSONATION_MAX_DURATION_MINUTES + 1,
+      }).success,
+    ).toBe(false);
+  });
+
+  test("rejects a missing reason", () => {
+    const { reason: _reason, ...withoutReason } = base;
+    expect(
+      impersonationCreateRequestSchema.safeParse({ ...withoutReason, duration_minutes: 10 })
+        .success,
+    ).toBe(false);
+  });
+
+  test("rejects a too-short reason", () => {
+    expect(
+      impersonationCreateRequestSchema.safeParse({ ...base, reason: "why", duration_minutes: 10 })
+        .success,
+    ).toBe(false);
+  });
+});

package/src/rbac.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import { userIdSchema } from "./primitives.js";
+
+/**
+ * Dashboard / Management API RBAC (design.md §27.2's role table, §11.2
+ * `workspace_members.role`).
+ */
+export const WORKSPACE_ROLES = [
+  "owner",
+  "admin",
+  "developer",
+  "support",
+  "billing",
+  "viewer",
+] as const;
+export const workspaceRoleSchema = z.enum(WORKSPACE_ROLES);
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+
+// ---------------------------------------------------------------------------
+// Scopes (design.md §26.1: "scope最小化" — Management API keys are granted a
+// minimal explicit scope list, not a raw role)
+// ---------------------------------------------------------------------------
+
+/**
+ * The full set of grantable Management API scopes. Most use the
+ * `<resource>:<action>` form; protocol capabilities such as `introspect` are
+ * standalone. This is the declarative permission vocabulary both Management
+ * API keys (design.md §11.12) and dashboard roles (design.md §27.2) use.
+ */
+export const MANAGEMENT_SCOPES = [
+  "workspaces:read",
+  "workspaces:write",
+  // `GET /workspaces/:workspaceId/members` (design.md §11.2, §27.3's
+  // Security settings screen, §27.2's RBAC table). See the `ROLE_SCOPES`
+  // doc comment below for which roles are granted this.
+  "workspace_members:read",
+  "projects:read",
+  "projects:write",
+  "environments:read",
+  "environments:write",
+  "clients:read",
+  "clients:write",
+  "clients:rotate_secret",
+  "connections:read",
+  "connections:write",
+  "domains:read",
+  "domains:write",
+  "users:read",
+  "users:write",
+  "users:block",
+  "users:delete",
+  "user_identities:read",
+  "user_identities:write",
+  "user_passkeys:read",
+  "user_passkeys:write",
+  "user_sessions:read",
+  "user_sessions:write",
+  "user_data_jobs:read",
+  "user_data_jobs:write",
+  "webhooks:read",
+  "webhooks:write",
+  "webhooks:rotate_secret",
+  "webhooks:test",
+  "audit_events:read",
+  "usage:read",
+  // Scoped Management API key permission for POST /oauth2/introspect
+  // (design.md §15.8); not a resource CRUD scope.
+  "introspect",
+  "billing:read",
+  "billing:write",
+  "api_keys:read",
+  "api_keys:write",
+  "impersonation:create",
+] as const;
+export const managementScopeSchema = z.enum(MANAGEMENT_SCOPES);
+export type ManagementScope = (typeof MANAGEMENT_SCOPES)[number];
+
+/**
+ * Scopes that let an actor change how a user authenticates: linking/unlinking
+ * a social identity or adding/removing a passkey (design.md §12.3/§12.5,
+ * §25's "credential"). Deliberately narrower than "anything about the user
+ * account" — e.g. blocking a user or editing their display name is an
+ * account-state/profile change, not a credential change.
+ *
+ * design.md §25: "support roleだけではcredentialを変更できない." §27.4 forbids
+ * the same category of action during impersonation ("credential変更...は禁止").
+ */
+export const CREDENTIAL_MUTATING_SCOPES = [
+  "user_identities:write",
+  "user_passkeys:write",
+] as const satisfies readonly ManagementScope[];
+
+/** design.md §27.4: impersonation additionally forbids billing and API key operations. */
+export const IMPERSONATION_FORBIDDEN_SCOPES = [
+  ...CREDENTIAL_MUTATING_SCOPES,
+  "billing:read",
+  "billing:write",
+  "api_keys:read",
+  "api_keys:write",
+] as const satisfies readonly ManagementScope[];
+
+/**
+ * design.md §27.2 role → permission table:
+ *
+ * | Role      | 権限 |
+ * |-----------|------|
+ * | Owner     | 全操作、課金、Workspace削除 |
+ * | Admin     | Project、Environment、ユーザー管理 |
+ * | Developer | Client、Connection、Domain、Webhook |
+ * | Support   | ユーザー閲覧、session失効 |
+ * | Billing   | 課金・使用量 |
+ * | Viewer    | 読み取りのみ |
+ *
+ * `workspace_members:read` grant decision (no dedicated row in the table
+ * above — the assignment that added `GET /workspaces/:workspaceId/members`
+ * requires a defensible reading of it): granted to owner/admin/support/
+ * billing/viewer, withheld from developer. The Developer table lists "Client,
+ * Connection, Domain, Webhook" resources, with `introspect` as a standalone
+ * OAuth capability for resource-server token validation. The test below
+ * ensures the developer role gets no other resource prefixes. Every other
+ * role either reads broadly (`viewer`, "読み取りのみ") or needs the roster for
+ * its work (`admin` administers the workspace; `support`/`billing` deal with
+ * the workspace's people and billing contacts day to day).
+ */
+export const ROLE_SCOPES: Readonly<Record<WorkspaceRole, readonly ManagementScope[]>> = {
+  owner: MANAGEMENT_SCOPES,
+  admin: [
+    "workspaces:read",
+    "workspace_members:read",
+    "projects:read",
+    "projects:write",
+    "environments:read",
+    "environments:write",
+    "introspect",
+    "users:read",
+    "users:write",
+    "users:block",
+    "users:delete",
+    "user_identities:read",
+    "user_identities:write",
+    "user_passkeys:read",
+    "user_passkeys:write",
+    "user_sessions:read",
+    "user_sessions:write",
+    "user_data_jobs:read",
+    "user_data_jobs:write",
+    "audit_events:read",
+    "impersonation:create",
+  ],
+  developer: [
+    "clients:read",
+    "introspect",
+    "clients:write",
+    "clients:rotate_secret",
+    "connections:read",
+    "connections:write",
+    "domains:read",
+    "domains:write",
+    "webhooks:read",
+    "webhooks:write",
+    "webhooks:rotate_secret",
+    "webhooks:test",
+  ],
+  support: [
+    "users:read",
+    "user_identities:read",
+    "user_passkeys:read",
+    "user_sessions:read",
+    "user_sessions:write",
+    "workspace_members:read",
+  ],
+  billing: [
+    "billing:read",
+    "billing:write",
+    "usage:read",
+    "workspaces:read",
+    "workspace_members:read",
+  ],
+  viewer: [
+    "workspaces:read",
+    "workspace_members:read",
+    "projects:read",
+    "environments:read",
+    "clients:read",
+    "connections:read",
+    "domains:read",
+    "users:read",
+    "user_identities:read",
+    "user_passkeys:read",
+    "user_sessions:read",
+    "user_data_jobs:read",
+    "webhooks:read",
+    "audit_events:read",
+    "usage:read",
+    "billing:read",
+    "api_keys:read",
+  ],
+};
+
+export const scopesForRole = (role: WorkspaceRole): readonly ManagementScope[] => ROLE_SCOPES[role];
+
+export const roleHasScope = (role: WorkspaceRole, scope: ManagementScope): boolean =>
+  ROLE_SCOPES[role].includes(scope);
+
+/** A scope is read-only when it grants inspection without changing a resource or token state. */
+export const isReadOnlyScope = (scope: ManagementScope): boolean =>
+  scope === "introspect" || scope.endsWith(":read");
+
+// ---------------------------------------------------------------------------
+// Impersonation (design.md §27.4)
+// ---------------------------------------------------------------------------
+
+/** design.md §27.4: "OwnerまたはAdmin" may start an impersonation session. */
+export const IMPERSONATION_ALLOWED_ROLES = [
+  "owner",
+  "admin",
+] as const satisfies readonly WorkspaceRole[];
+export const impersonationAllowedRoleSchema = z.enum(IMPERSONATION_ALLOWED_ROLES);
+export type ImpersonationAllowedRole = (typeof IMPERSONATION_ALLOWED_ROLES)[number];
+
+/** design.md §27.4: "最大15分". */
+export const IMPERSONATION_MAX_DURATION_MINUTES = 15;
+
+/** design.md §27.4: "理由入力" is a required, non-empty justification. */
+export const impersonationReasonSchema = z.string().min(10).max(1000);
+
+export const impersonationCreateRequestSchema = z.strictObject({
+  user_id: userIdSchema,
+  reason: impersonationReasonSchema,
+  duration_minutes: z.number().int().min(1).max(IMPERSONATION_MAX_DURATION_MINUTES),
+});
+export type ImpersonationCreateRequest = z.infer<typeof impersonationCreateRequestSchema>;
+
+/**
+ * design.md §27.4: "UIに常時banner", "全操作をactorとimpersonated userの両方で
+ * 監査". The response carries both identities so the dashboard can render the
+ * mandatory banner and so every subsequent action can be dual-audited.
+ */
+export const impersonationSessionSchema = z.strictObject({
+  actor_user_id: userIdSchema,
+  impersonated_user_id: userIdSchema,
+  reason: impersonationReasonSchema,
+  started_at: z.iso.datetime(),
+  expires_at: z.iso.datetime(),
+  forbidden_scopes: z.array(managementScopeSchema),
+});
+export type ImpersonationSession = z.infer<typeof impersonationSessionSchema>;
+
+export const impersonationCreateResponseSchema = impersonationSessionSchema;
+export type ImpersonationCreateResponse = z.infer<typeof impersonationCreateResponseSchema>;