@smartcrab/contracts-management 0.1.0

package/dist/webhooks.js

@@ -0,0 +1,134 @@
+import { httpsUrlSchema } from "@smartcrab/contracts-public";
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { deliveryIdSchema, environmentIdSchema, eventIdSchema, webhookIdSchema, } from "./primitives.js";
+/**
+ * `webhook_endpoints` (design.md §11.13) and the Customer Webhook event
+ * catalog (design.md §29.4's "イベント例" list, treated as the canonical
+ * enum since no other source enumerates event types). `secret_ciphertext`/
+ * `secret_iv` are excluded per the assignment's forbidden-field list; like
+ * `management_api_keys` (§11.12) and client secrets, the plaintext webhook
+ * signing secret is shown exactly once, on create/rotate.
+ */
+export const WEBHOOK_EVENT_TYPES = [
+    "user.created",
+    "user.updated",
+    "user.deleted",
+    "user.blocked",
+    "identity.linked",
+    "identity.unlinked",
+    "passkey.created",
+    "passkey.deleted",
+    "session.created",
+    "session.revoked",
+    "login.succeeded",
+    "login.failed",
+    "email.delivery.bounced",
+    "mau.threshold_reached",
+];
+export const webhookEventTypeSchema = z.enum(WEBHOOK_EVENT_TYPES);
+export const WEBHOOK_STATUSES = ["active", "disabled"];
+export const webhookStatusSchema = z.enum(WEBHOOK_STATUSES);
+export const webhookSchema = z.strictObject({
+    id: webhookIdSchema,
+    environment_id: environmentIdSchema,
+    url: httpsUrlSchema,
+    event_types: z.array(webhookEventTypeSchema).min(1),
+    status: webhookStatusSchema,
+    created_at: z.iso.datetime(),
+    updated_at: z.iso.datetime(),
+});
+// ---------------------------------------------------------------------------
+// GET /webhooks
+// ---------------------------------------------------------------------------
+export const webhookListQuerySchema = paginationQuerySchema.extend({
+    environment_id: environmentIdSchema,
+});
+export const webhookListResponseSchema = cursorPageSchema(webhookSchema);
+// ---------------------------------------------------------------------------
+// POST /webhooks
+// ---------------------------------------------------------------------------
+export const webhookCreateRequestSchema = z.strictObject({
+    environment_id: environmentIdSchema,
+    url: httpsUrlSchema,
+    event_types: z.array(webhookEventTypeSchema).min(1),
+});
+/** One-time plaintext signing secret (design.md §11.12's display-once rule, applied here too; §29.4 HMAC). */
+export const webhookCreateResponseSchema = webhookSchema.extend({
+    secret: z.string().min(1),
+});
+// ---------------------------------------------------------------------------
+// PATCH /webhooks/:webhookId
+// ---------------------------------------------------------------------------
+export const webhookUpdateRequestSchema = z.strictObject({
+    url: httpsUrlSchema.optional(),
+    event_types: z.array(webhookEventTypeSchema).min(1).optional(),
+    status: webhookStatusSchema.optional(),
+});
+export const webhookUpdateResponseSchema = webhookSchema;
+// ---------------------------------------------------------------------------
+// DELETE /webhooks/:webhookId
+// ---------------------------------------------------------------------------
+export const webhookDeleteResponseSchema = z.strictObject({
+    id: webhookIdSchema,
+    deleted: z.literal(true),
+});
+// ---------------------------------------------------------------------------
+// POST /webhooks/:webhookId/rotate-secret
+// ---------------------------------------------------------------------------
+export const webhookRotateSecretRequestSchema = z.strictObject({});
+export const webhookRotateSecretResponseSchema = z.strictObject({
+    id: webhookIdSchema,
+    secret: z.string().min(1),
+    rotated_at: z.iso.datetime(),
+});
+// ---------------------------------------------------------------------------
+// POST /webhooks/:webhookId/test
+// ---------------------------------------------------------------------------
+export const webhookTestRequestSchema = z.strictObject({
+    /** Defaults to a synthetic event if omitted; must be one of this webhook's subscribed `event_types`. */
+    event_type: webhookEventTypeSchema.optional(),
+});
+/** design.md §29.4: "2xxだけ成功". `delivered` reports whether the endpoint returned 2xx. */
+export const webhookTestResponseSchema = z.strictObject({
+    delivered: z.boolean(),
+    response_status: z.number().int().min(100).max(599).nullable(),
+    response_time_ms: z.number().int().nonnegative().nullable(),
+    requested_at: z.iso.datetime(),
+});
+// ---------------------------------------------------------------------------
+// GET /webhooks/:webhookId/deliveries
+// ---------------------------------------------------------------------------
+/**
+ * `webhook_delivery_history` (design.md §29.4, §10.10): one row per delivery
+ * attempt. Deliberately excludes any request/response body, header, or
+ * signature — only status/attempt/response code/duration are ever recorded
+ * or exposed here, matching `@smartcrab/database-control`'s
+ * `WebhookDeliveryHistoryRecord`.
+ */
+export const WEBHOOK_DELIVERY_STATUSES = ["pending", "delivered", "failed", "exhausted"];
+export const webhookDeliveryStatusSchema = z.enum(WEBHOOK_DELIVERY_STATUSES);
+export const webhookDeliverySchema = z.strictObject({
+    id: deliveryIdSchema,
+    webhook_id: webhookIdSchema,
+    event_id: eventIdSchema,
+    /**
+     * Not `webhookEventTypeSchema` (that closed enum belongs to a webhook's
+     * *subscription* list on `webhookSchema` above): history rows are retained
+     * 90 days (design.md §10.10) and must stay parseable even if the event
+     * catalog changes after a row was written, so this is a plain non-empty
+     * string.
+     */
+    event_type: z.string().min(1),
+    attempt: z.number().int().positive(),
+    status: webhookDeliveryStatusSchema,
+    response_status_code: z.number().int().min(100).max(599).nullable(),
+    duration_ms: z.number().int().nonnegative(),
+    occurred_at: z.iso.datetime(),
+});
+export const webhookDeliveryListQuerySchema = paginationQuerySchema.extend({
+    status: webhookDeliveryStatusSchema.optional(),
+    occurred_after: z.iso.datetime().optional(),
+    occurred_before: z.iso.datetime().optional(),
+});
+export const webhookDeliveryListResponseSchema = cursorPageSchema(webhookDeliverySchema);

package/dist/workspaces.d.ts

@@ -0,0 +1,172 @@
+import { z } from "zod";
+/**
+ * `workspaces` (design.md §11.1, §7.1). No secret/internal-routing columns
+ * exist on this table to exclude; `stripe_customer_id` is an opaque Stripe
+ * identifier (not a secret — it carries no ability to act on the customer)
+ * and is useful to dashboard/billing UI, so it is exposed as nullable.
+ */
+export declare const WORKSPACE_STATUSES: readonly ["active", "past_due", "suspended", "deleted"];
+export declare const workspaceStatusSchema: z.ZodEnum<{
+    active: "active";
+    deleted: "deleted";
+    suspended: "suspended";
+    past_due: "past_due";
+}>;
+export type WorkspaceStatus = (typeof WORKSPACE_STATUSES)[number];
+export declare const workspaceSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        suspended: "suspended";
+        past_due: "past_due";
+    }>;
+    stripe_customer_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    deleted_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type Workspace = z.infer<typeof workspaceSchema>;
+export declare const workspaceListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        suspended: "suspended";
+        past_due: "past_due";
+    }>>;
+}, z.core.$strip>;
+export type WorkspaceListQuery = z.infer<typeof workspaceListQuerySchema>;
+export declare const workspaceListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        slug: z.ZodString;
+        status: z.ZodEnum<{
+            active: "active";
+            deleted: "deleted";
+            suspended: "suspended";
+            past_due: "past_due";
+        }>;
+        stripe_customer_id: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        deleted_at: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceListResponse = z.infer<typeof workspaceListResponseSchema>;
+/** `slug` is optional: when omitted, the server derives one from `name` (design.md §11.1 `slug UNIQUE`). */
+export declare const workspaceCreateRequestSchema: z.ZodObject<{
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceCreateRequest = z.infer<typeof workspaceCreateRequestSchema>;
+export declare const workspaceCreateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        suspended: "suspended";
+        past_due: "past_due";
+    }>;
+    stripe_customer_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    deleted_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type WorkspaceCreateResponse = z.infer<typeof workspaceCreateResponseSchema>;
+export declare const workspaceGetResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        suspended: "suspended";
+        past_due: "past_due";
+    }>;
+    stripe_customer_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    deleted_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type WorkspaceGetResponse = z.infer<typeof workspaceGetResponseSchema>;
+/**
+ * `status` is deliberately excluded: workspace suspension/deletion are
+ * billing- and Owner-driven lifecycle transitions (design.md §27.2 "Owner: 全
+ * 操作、課金、Workspace削除"), not a generic field patch.
+ */
+export declare const workspaceUpdateRequestSchema: z.ZodObject<{
+    name: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceUpdateRequest = z.infer<typeof workspaceUpdateRequestSchema>;
+export declare const workspaceUpdateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodEnum<{
+        active: "active";
+        deleted: "deleted";
+        suspended: "suspended";
+        past_due: "past_due";
+    }>;
+    stripe_customer_id: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    deleted_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type WorkspaceUpdateResponse = z.infer<typeof workspaceUpdateResponseSchema>;
+/**
+ * `workspace_members` (design.md §11.2, §27.2). Exposes only the fields the
+ * assignment enumerates — `platform_user_id`/`role`/`created_at`/
+ * `updated_at` — no credential or session material (this table carries none
+ * anyway; those four columns are its entire shape). `platform_user_id` is a
+ * plain non-empty string rather than `userIdSchema`: it identifies a
+ * platform (dashboard) user of this Control Plane's own dogfooded
+ * Environment (design.md §27.1), a distinct identifier space from the
+ * `usr_...`-pattern end users `userIdSchema` models elsewhere in this
+ * package.
+ */
+export declare const workspaceMemberSchema: z.ZodObject<{
+    platform_user_id: z.ZodString;
+    role: z.ZodEnum<{
+        owner: "owner";
+        admin: "admin";
+        developer: "developer";
+        support: "support";
+        billing: "billing";
+        viewer: "viewer";
+    }>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type WorkspaceMember = z.infer<typeof workspaceMemberSchema>;
+export declare const workspaceMemberListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type WorkspaceMemberListQuery = z.infer<typeof workspaceMemberListQuerySchema>;
+export declare const workspaceMemberListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        platform_user_id: z.ZodString;
+        role: z.ZodEnum<{
+            owner: "owner";
+            admin: "admin";
+            developer: "developer";
+            support: "support";
+            billing: "billing";
+            viewer: "viewer";
+        }>;
+        created_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type WorkspaceMemberListResponse = z.infer<typeof workspaceMemberListResponseSchema>;

package/dist/workspaces.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { slugSchema, workspaceIdSchema } from "./primitives.js";
+import { workspaceRoleSchema } from "./rbac.js";
+/**
+ * `workspaces` (design.md §11.1, §7.1). No secret/internal-routing columns
+ * exist on this table to exclude; `stripe_customer_id` is an opaque Stripe
+ * identifier (not a secret — it carries no ability to act on the customer)
+ * and is useful to dashboard/billing UI, so it is exposed as nullable.
+ */
+export const WORKSPACE_STATUSES = ["active", "past_due", "suspended", "deleted"];
+export const workspaceStatusSchema = z.enum(WORKSPACE_STATUSES);
+export const workspaceSchema = z.strictObject({
+    id: workspaceIdSchema,
+    name: z.string().min(1).max(200),
+    slug: slugSchema,
+    status: workspaceStatusSchema,
+    stripe_customer_id: z.string().min(1).nullable(),
+    created_at: z.iso.datetime(),
+    updated_at: z.iso.datetime(),
+    deleted_at: z.iso.datetime().nullable(),
+});
+// ---------------------------------------------------------------------------
+// GET /workspaces
+// ---------------------------------------------------------------------------
+export const workspaceListQuerySchema = paginationQuerySchema.extend({
+    status: workspaceStatusSchema.optional(),
+});
+export const workspaceListResponseSchema = cursorPageSchema(workspaceSchema);
+// ---------------------------------------------------------------------------
+// POST /workspaces
+// ---------------------------------------------------------------------------
+/** `slug` is optional: when omitted, the server derives one from `name` (design.md §11.1 `slug UNIQUE`). */
+export const workspaceCreateRequestSchema = z.strictObject({
+    name: z.string().min(1).max(200),
+    slug: slugSchema.optional(),
+});
+export const workspaceCreateResponseSchema = workspaceSchema;
+// ---------------------------------------------------------------------------
+// GET /workspaces/:workspaceId
+// ---------------------------------------------------------------------------
+export const workspaceGetResponseSchema = workspaceSchema;
+// ---------------------------------------------------------------------------
+// PATCH /workspaces/:workspaceId
+// ---------------------------------------------------------------------------
+/**
+ * `status` is deliberately excluded: workspace suspension/deletion are
+ * billing- and Owner-driven lifecycle transitions (design.md §27.2 "Owner: 全
+ * 操作、課金、Workspace削除"), not a generic field patch.
+ */
+export const workspaceUpdateRequestSchema = z.strictObject({
+    name: z.string().min(1).max(200).optional(),
+    slug: slugSchema.optional(),
+});
+export const workspaceUpdateResponseSchema = workspaceSchema;
+// ---------------------------------------------------------------------------
+// GET /workspaces/:workspaceId/members
+// ---------------------------------------------------------------------------
+/**
+ * `workspace_members` (design.md §11.2, §27.2). Exposes only the fields the
+ * assignment enumerates — `platform_user_id`/`role`/`created_at`/
+ * `updated_at` — no credential or session material (this table carries none
+ * anyway; those four columns are its entire shape). `platform_user_id` is a
+ * plain non-empty string rather than `userIdSchema`: it identifies a
+ * platform (dashboard) user of this Control Plane's own dogfooded
+ * Environment (design.md §27.1), a distinct identifier space from the
+ * `usr_...`-pattern end users `userIdSchema` models elsewhere in this
+ * package.
+ */
+export const workspaceMemberSchema = z.strictObject({
+    platform_user_id: z.string().min(1),
+    role: workspaceRoleSchema,
+    created_at: z.iso.datetime(),
+    updated_at: z.iso.datetime(),
+});
+export const workspaceMemberListQuerySchema = paginationQuerySchema;
+export const workspaceMemberListResponseSchema = cursorPageSchema(workspaceMemberSchema);

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@smartcrab/contracts-management",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "development": "./src/*.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "4.4.3",
+    "@smartcrab/contracts-public": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.build.json"
+  }
+}

package/src/api-keys.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "vitest";
+import {
+  managementApiKeyCreateRequestSchema,
+  managementApiKeyCreateResponseSchema,
+  managementApiKeyListResponseSchema,
+  managementApiKeySchema,
+} from "./api-keys.js";
+
+const VALID_KEY = {
+  id: `mky_${"a".repeat(32)}`,
+  workspace_id: `wsp_${"a".repeat(32)}`,
+  environment_id: null,
+  name: "CI deploy key",
+  prefix: "sk_live_ab12",
+  scopes: ["clients:read", "clients:write"],
+  last_used_at: null,
+  expires_at: null,
+  revoked_at: null,
+  created_by: `usr_${"a".repeat(32)}`,
+  created_at: "2026-08-02T08:10:00Z",
+};
+
+describe("managementApiKeySchema (design.md §11.12) never exposes key_mac", () => {
+  test("accepts a valid key", () => {
+    expect(managementApiKeySchema.safeParse(VALID_KEY).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking key_mac)", () => {
+    expect(managementApiKeySchema.safeParse({ ...VALID_KEY, key_mac: "abc" }).success).toBe(false);
+  });
+
+  test("rejects an unknown scope", () => {
+    expect(
+      managementApiKeySchema.safeParse({ ...VALID_KEY, scopes: ["not_a_scope"] }).success,
+    ).toBe(false);
+  });
+});
+
+describe("management API key create response includes the one-time secret, list does not", () => {
+  test("create response requires a well-formed sk_live_/sk_test_ secret (design.md §26.1)", () => {
+    expect(
+      managementApiKeyCreateResponseSchema.safeParse({
+        ...VALID_KEY,
+        secret: `sk_live_${"a".repeat(24)}`,
+      }).success,
+    ).toBe(true);
+    expect(
+      managementApiKeyCreateResponseSchema.safeParse({
+        ...VALID_KEY,
+        secret: "not-the-right-format",
+      }).success,
+    ).toBe(false);
+  });
+
+  test("list response rejects an item carrying a secret", () => {
+    expect(
+      managementApiKeyListResponseSchema.safeParse({
+        items: [{ ...VALID_KEY, secret: `sk_live_${"a".repeat(24)}` }],
+        next_cursor: null,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("managementApiKeyCreateRequestSchema", () => {
+  test("requires at least one scope (design.md §26.1 'scope最小化')", () => {
+    expect(
+      managementApiKeyCreateRequestSchema.safeParse({
+        workspace_id: VALID_KEY.workspace_id,
+        name: "Empty scopes",
+        scopes: [],
+      }).success,
+    ).toBe(false);
+  });
+});
+describe("Management API key token introspection scope", () => {
+  test("allows an introspection-only key", () => {
+    const parsed = managementApiKeyCreateRequestSchema.safeParse({
+      workspace_id: VALID_KEY.workspace_id,
+      name: "Resource server introspection",
+      scopes: ["introspect"],
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) expect(parsed.data.scopes).toEqual(["introspect"]);
+  });
+});

package/src/api-keys.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { apiKeyIdSchema, environmentIdSchema, workspaceIdSchema } from "./primitives.js";
+import { MANAGEMENT_SCOPES, managementScopeSchema } from "./rbac.js";
+
+/**
+ * `management_api_keys` (design.md §11.12, §26.1).
+ *
+ * DEVIATION: design.md §26.2's route list does not enumerate `/api-keys`
+ * routes explicitly, but §26.1 ("Management API key", "scope最小化"),
+ * §11.12 (the table + "Secretは作成時に1回だけ表示する"), and this
+ * assignment's requirement 4 all describe the resource, so it is modeled
+ * here the same way every other enumerated resource is (list/create + a
+ * revoke action), following the create/rotate-secret pattern used for
+ * `clients` and `webhooks`.
+ *
+ * `key_mac` (the forbidden HMAC-of-the-full-key column) is excluded from
+ * every schema below; `prefix` is kept (it exists specifically to be a safe,
+ * non-secret display fragment, design.md §11.12).
+ */
+
+/** design.md §26.1: `Authorization: Bearer sk_live_...` / test-mode keys use `sk_test_`. */
+export const MANAGEMENT_API_KEY_LIVE_PREFIX = "sk_live_";
+export const MANAGEMENT_API_KEY_TEST_PREFIX = "sk_test_";
+
+/**
+ * Length of the non-secret display prefix stored in `management_api_keys.key_prefix`
+ * (`sk_live_` / `sk_test_` + the first 4 opaque chars). Prefix lookup slices the
+ * presented bearer secret to exactly this many characters. Both mode literals are
+ * the same length, so one value covers live and test keys.
+ */
+export const MANAGEMENT_API_KEY_PREFIX_LENGTH = MANAGEMENT_API_KEY_LIVE_PREFIX.length + 4;
+
+/** The full bearer secret's wire format: `sk_(live|test)_<opaque>`. Shown only on create/rotate. */
+export const managementApiKeySecretSchema = z
+  .string()
+  .regex(/^sk_(?:live|test)_[A-Za-z0-9_-]{20,}$/);
+
+export const managementApiKeySchema = z.strictObject({
+  id: apiKeyIdSchema,
+  workspace_id: workspaceIdSchema,
+  /** design.md §11.12 `environment_id NULLABLE`: a workspace-wide key when absent. */
+  environment_id: environmentIdSchema.nullable(),
+  name: z.string().min(1).max(200),
+  /** The non-secret display prefix, e.g. `sk_live_ab12`. */
+  prefix: z.string().min(1),
+  scopes: z.array(managementScopeSchema).min(1),
+  last_used_at: z.iso.datetime().nullable(),
+  expires_at: z.iso.datetime().nullable(),
+  revoked_at: z.iso.datetime().nullable(),
+  created_by: z.string().min(1),
+  created_at: z.iso.datetime(),
+});
+export type ManagementApiKey = z.infer<typeof managementApiKeySchema>;
+
+// ---------------------------------------------------------------------------
+// GET /api-keys
+// ---------------------------------------------------------------------------
+
+export const managementApiKeyListQuerySchema = paginationQuerySchema.extend({
+  workspace_id: workspaceIdSchema,
+  environment_id: environmentIdSchema.optional(),
+});
+export type ManagementApiKeyListQuery = z.infer<typeof managementApiKeyListQuerySchema>;
+
+export const managementApiKeyListResponseSchema = cursorPageSchema(managementApiKeySchema);
+export type ManagementApiKeyListResponse = z.infer<typeof managementApiKeyListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /api-keys
+// ---------------------------------------------------------------------------
+
+export const managementApiKeyCreateRequestSchema = z.strictObject({
+  workspace_id: workspaceIdSchema,
+  name: z.string().min(1).max(200),
+  /** design.md §26.1 "scope最小化": callers must explicitly enumerate at least one scope. */
+  scopes: z.array(managementScopeSchema).min(1).max(MANAGEMENT_SCOPES.length),
+  environment_id: environmentIdSchema.optional(),
+  expires_at: z.iso.datetime().optional(),
+});
+export type ManagementApiKeyCreateRequest = z.infer<typeof managementApiKeyCreateRequestSchema>;
+
+/** design.md §11.12: "Secretは作成時に1回だけ表示する。" `secret` never appears again after this response. */
+export const managementApiKeyCreateResponseSchema = managementApiKeySchema.extend({
+  secret: managementApiKeySecretSchema,
+});
+export type ManagementApiKeyCreateResponse = z.infer<typeof managementApiKeyCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// Revoke (DELETE-shaped action; not in the §26.2 route list — see DEVIATION above)
+// ---------------------------------------------------------------------------
+
+export const managementApiKeyRevokeResponseSchema = z.strictObject({
+  id: apiKeyIdSchema,
+  revoked: z.literal(true),
+});
+export type ManagementApiKeyRevokeResponse = z.infer<typeof managementApiKeyRevokeResponseSchema>;

package/src/audit-events.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "vitest";
+import { auditEventListQuerySchema, auditEventSchema } from "./audit-events.js";
+
+const VALID_EVENT = {
+  id: `evt_${"a".repeat(32)}`,
+  environment_id: `env_${"a".repeat(32)}`,
+  workspace_id: `wsp_${"a".repeat(32)}`,
+  actor_type: "workspace_member",
+  actor_id: `usr_${"a".repeat(32)}`,
+  action: "client.updated",
+  subject_type: "client",
+  subject_id: `cli_${"a".repeat(32)}`,
+  result: "success",
+  request_id: `req_${"a".repeat(32)}`,
+  metadata: {},
+  created_at: "2026-08-02T08:10:00Z",
+};
+
+describe("auditEventSchema (design.md §12.11)", () => {
+  test("accepts a valid audit event", () => {
+    expect(auditEventSchema.safeParse(VALID_EVENT).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking auth_partition_id)", () => {
+    expect(auditEventSchema.safeParse({ ...VALID_EVENT, auth_partition_id: "prt_1" }).success).toBe(
+      false,
+    );
+  });
+
+  test("rejects an unknown actor_type", () => {
+    expect(auditEventSchema.safeParse({ ...VALID_EVENT, actor_type: "robot" }).success).toBe(false);
+  });
+});
+
+describe("auditEventListQuerySchema pagination", () => {
+  test("rejects a page size above the max of 100", () => {
+    expect(
+      auditEventListQuerySchema.safeParse({
+        environment_id: VALID_EVENT.environment_id,
+        limit: 500,
+      }).success,
+    ).toBe(false);
+  });
+});