@smartcrab/contracts-management 0.1.0

package/src/common.ts

@@ -0,0 +1,127 @@
+import { z } from "zod";
+
+/**
+ * Common Management API envelope conventions (design.md §26.3):
+ *
+ * - cursor pagination, max page size 100
+ * - write APIs support `Idempotency-Key`
+ * - updates support ETag / `If-Match`
+ * - a Request ID is attached to every response
+ * - errors are returned as RFC 9457 Problem Details
+ *
+ * `request_id`: design.md §26.3's Problem Details example embeds
+ * `request_id` inside the error body. For success responses this package
+ * does not duplicate `request_id` into every resource/list schema — doing so
+ * would force every list item and every nested object to carry a redundant
+ * copy. Instead, success responses attach it the same way
+ * `@smartcrab/result`'s `problemDetailsResponse` already does for errors:
+ * an `X-Request-Id` response header (`requestIdHeaderSchema` below). Routes
+ * that need the id in the JSON body too may extend a resource schema with
+ * `problemDetailsSchema`'s `request_id` field; the header is the one
+ * guarantee this package encodes as "attached to all responses".
+ */
+
+// ---------------------------------------------------------------------------
+// Pagination (design.md §26.3: "cursor pagination", "最大page size 100")
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_PAGE_SIZE = 25;
+export const MAX_PAGE_SIZE = 100;
+
+/**
+ * Query parameters shared by every `GET` list route. `limit` is coerced from
+ * its wire representation (a query string) to a number so callers can parse
+ * `URLSearchParams` values directly.
+ */
+export const paginationQuerySchema = z.object({
+  cursor: z.string().min(1).max(2048).optional(),
+  limit: z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).default(DEFAULT_PAGE_SIZE),
+});
+export type PaginationQuery = z.infer<typeof paginationQuerySchema>;
+
+/**
+ * Generic cursor-paginated list envelope: `{ items, next_cursor }`.
+ * `next_cursor` is `null` once the caller has reached the last page.
+ */
+export const cursorPageSchema = <ItemSchema extends z.ZodType>(itemSchema: ItemSchema) =>
+  z.strictObject({
+    items: z.array(itemSchema),
+    next_cursor: z.string().min(1).nullable(),
+  });
+export type CursorPage<Item> = {
+  readonly items: readonly Item[];
+  readonly next_cursor: string | null;
+};
+
+// ---------------------------------------------------------------------------
+// Idempotency-Key (design.md §26.3: "write APIは`Idempotency-Key`対応")
+// ---------------------------------------------------------------------------
+
+export const idempotencyKeySchema = z.string().min(1).max(255);
+
+/** Header carried by every `POST`/`PATCH`/`DELETE` write request. */
+export const idempotencyKeyHeaderSchema = z.strictObject({
+  "idempotency-key": idempotencyKeySchema,
+});
+export type IdempotencyKeyHeader = z.infer<typeof idempotencyKeyHeaderSchema>;
+
+// ---------------------------------------------------------------------------
+// ETag / If-Match (design.md §26.3: "updateはETag / `If-Match`対応")
+// ---------------------------------------------------------------------------
+
+/** An opaque entity tag, optionally weak (`W/"..."`) or quoted per RFC 9110 §8.8.3. */
+export const etagSchema = z.string().min(1).max(512);
+export type ETag = z.infer<typeof etagSchema>;
+
+/** Header carried by every conditional `PATCH`/`DELETE` request. */
+export const ifMatchHeaderSchema = z.strictObject({
+  "if-match": etagSchema,
+});
+export type IfMatchHeader = z.infer<typeof ifMatchHeaderSchema>;
+
+// ---------------------------------------------------------------------------
+// Request ID (design.md §26.3: "Request IDを全レスポンスへ付与")
+// ---------------------------------------------------------------------------
+
+/** `req_...` (design.md §7.5 / `@smartcrab/identifiers` `ID_PREFIXES.request`). */
+export const requestIdSchema = z.string().regex(/^req_[a-z2-7]{32}$/);
+export type RequestId = z.infer<typeof requestIdSchema>;
+
+export const requestIdHeaderSchema = z.strictObject({
+  "x-request-id": requestIdSchema,
+});
+export type RequestIdHeader = z.infer<typeof requestIdHeaderSchema>;
+
+// ---------------------------------------------------------------------------
+// Problem Details (design.md §26.3, RFC 9457)
+// ---------------------------------------------------------------------------
+
+/**
+ * Matches `@smartcrab/result`'s `ProblemDetails` interface shape exactly
+ * (this package does not import `@smartcrab/result`, per assignment
+ * rules, so the shape is redefined here as a zod schema for request/response
+ * contract validation rather than reused as a TS type).
+ *
+ * ```json
+ * {
+ *   "type": "https://docs.example-auth.com/errors/invalid-redirect-uri",
+ *   "title": "Invalid redirect URI",
+ *   "status": 400,
+ *   "detail": "The redirect URI is not registered for this client.",
+ *   "code": "invalid_redirect_uri",
+ *   "request_id": "req_xxx"
+ * }
+ * ```
+ *
+ * Deliberately NOT `z.strictObject`: RFC 9457 explicitly allows arbitrary
+ * extension members alongside the standard ones.
+ */
+export const problemDetailsSchema = z.object({
+  type: z.string().min(1),
+  title: z.string().min(1),
+  status: z.number().int().min(100).max(599),
+  detail: z.string().optional(),
+  code: z.string().optional(),
+  request_id: requestIdSchema.optional(),
+});
+export type ProblemDetails = z.infer<typeof problemDetailsSchema>;

package/src/connections.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import {
+  connectionCreateRequestSchema,
+  connectionCreateResponseSchema,
+  connectionSchema,
+} from "./connections.js";
+
+const VALID_CONNECTION = {
+  id: `con_${"a".repeat(32)}`,
+  environment_id: `env_${"a".repeat(32)}`,
+  provider: "google",
+  mode: "managed",
+  provider_key: "google-default",
+  issuer: null,
+  provider_client_id: "123456.apps.googleusercontent.com",
+  scopes: ["email", "profile"],
+  profile_mapping: {},
+  status: "active",
+  owner_confirmed: true,
+  created_at: "2026-08-02T08:10:00Z",
+  updated_at: "2026-08-02T08:10:00Z",
+};
+
+describe("connectionSchema (design.md §11.10)", () => {
+  test("accepts a valid connection", () => {
+    expect(connectionSchema.safeParse(VALID_CONNECTION).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking secret_ciphertext)", () => {
+    expect(
+      connectionSchema.safeParse({ ...VALID_CONNECTION, secret_ciphertext: "abc" }).success,
+    ).toBe(false);
+  });
+
+  test("rejects secret_key_version leaking through (internal encryption generation)", () => {
+    expect(connectionSchema.safeParse({ ...VALID_CONNECTION, secret_key_version: 1 }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe("connectionCreateRequestSchema / connectionCreateResponseSchema", () => {
+  test("create request accepts a write-only provider_client_secret", () => {
+    expect(
+      connectionCreateRequestSchema.safeParse({
+        environment_id: VALID_CONNECTION.environment_id,
+        provider: "generic_oidc",
+        mode: "byo",
+        provider_key: "acme-sso",
+        issuer: "https://sso.acme.example",
+        provider_client_id: "abc",
+        provider_client_secret: "super-secret-value",
+      }).success,
+    ).toBe(true);
+  });
+
+  test("create response never echoes provider_client_secret back", () => {
+    expect(
+      connectionCreateResponseSchema.safeParse({
+        ...VALID_CONNECTION,
+        provider_client_secret: "leaked",
+      }).success,
+    ).toBe(false);
+  });
+});

package/src/connections.ts

@@ -0,0 +1,134 @@
+import { httpsUrlSchema, socialProviderSchema } from "@smartcrab/contracts-public";
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { connectionIdSchema, environmentIdSchema } from "./primitives.js";
+
+/**
+ * `provider_connections` (design.md §11.10, §20). `secret_ciphertext`,
+ * `secret_iv`, and `secret_key_version` are excluded: the first two per the
+ * assignment's forbidden-field list, the third as the internal encryption
+ * key-rotation generation for those ciphertexts — the same "internal
+ * routing/security machinery" category, not a resource attribute a
+ * dashboard/API consumer needs.
+ *
+ * The provider's own OAuth `client_id` (design.md §11.10's `client_id`
+ * column) is renamed here to `provider_client_id` to avoid colliding with
+ * this platform's own `Client` resource (`clients.id`, §11.5) — the two are
+ * unrelated identifiers that happen to share a column name in the schema.
+ */
+export const CONNECTION_MODES = ["managed", "byo"] as const;
+export const connectionModeSchema = z.enum(CONNECTION_MODES);
+export type ConnectionMode = (typeof CONNECTION_MODES)[number];
+
+export const CONNECTION_STATUSES = ["active", "disabled"] as const;
+export const connectionStatusSchema = z.enum(CONNECTION_STATUSES);
+export type ConnectionStatus = (typeof CONNECTION_STATUSES)[number];
+
+/** A single non-whitespace OAuth scope token requested from the upstream provider. */
+const providerScopeSchema = z.string().min(1).max(100).regex(/^\S+$/);
+
+/** design.md §11.10 `provider_key`: distinguishes multiple connections of the same provider per environment. */
+const providerKeySchema = z
+  .string()
+  .min(1)
+  .max(100)
+  .regex(/^[a-z0-9]+(?:[_-][a-z0-9]+)*$/);
+
+/** Maps this platform's normalized profile fields to the provider's own claim/attribute names. */
+const profileMappingSchema = z.record(z.string(), z.string());
+
+export const connectionSchema = z.strictObject({
+  id: connectionIdSchema,
+  environment_id: environmentIdSchema,
+  provider: socialProviderSchema,
+  mode: connectionModeSchema,
+  provider_key: providerKeySchema,
+  /** Only meaningful for `provider: "generic_oidc"` (design.md §11.10 `issuer NULLABLE`). */
+  issuer: httpsUrlSchema.nullable(),
+  provider_client_id: z.string().min(1),
+  scopes: z.array(providerScopeSchema).max(20),
+  profile_mapping: profileMappingSchema,
+  status: connectionStatusSchema,
+  /**
+   * design.md §20.3: "Dashboard上で所有者が明示確認するまでConnectionを有効化
+   * しない" — a `generic_oidc` connection's owner-supplied issuer is a real
+   * SSRF surface, so it stays unusable until the Dashboard owner explicitly
+   * confirms it here. Always `true` for every other provider (nothing to
+   * confirm).
+   */
+  owner_confirmed: z.boolean(),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+});
+export type Connection = z.infer<typeof connectionSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /connections
+// ---------------------------------------------------------------------------
+
+export const connectionListQuerySchema = paginationQuerySchema.extend({
+  environment_id: environmentIdSchema,
+  provider: socialProviderSchema.optional(),
+});
+export type ConnectionListQuery = z.infer<typeof connectionListQuerySchema>;
+
+export const connectionListResponseSchema = cursorPageSchema(connectionSchema);
+export type ConnectionListResponse = z.infer<typeof connectionListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /connections
+// ---------------------------------------------------------------------------
+
+/**
+ * `provider_client_secret` is write-only: it is the plaintext OAuth client
+ * secret issued by the upstream provider (§20.4 "Secret暗号化" — the server
+ * encrypts it into `secret_ciphertext` before persisting). Unlike the
+ * platform-generated client/webhook/API-key secrets, this value is supplied
+ * by the caller, not generated by the server, so it never appears in any
+ * response, not even a one-time-display response.
+ */
+export const connectionCreateRequestSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  provider: socialProviderSchema,
+  mode: connectionModeSchema,
+  provider_key: providerKeySchema,
+  issuer: httpsUrlSchema.optional(),
+  provider_client_id: z.string().min(1),
+  provider_client_secret: z.string().min(1),
+  scopes: z.array(providerScopeSchema).max(20).default([]),
+  profile_mapping: profileMappingSchema.default({}),
+});
+export type ConnectionCreateRequest = z.infer<typeof connectionCreateRequestSchema>;
+
+export const connectionCreateResponseSchema = connectionSchema;
+export type ConnectionCreateResponse = z.infer<typeof connectionCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /connections/:connectionId
+// ---------------------------------------------------------------------------
+
+export const connectionUpdateRequestSchema = z.strictObject({
+  issuer: httpsUrlSchema.optional(),
+  provider_client_id: z.string().min(1).optional(),
+  /** Write-only; omit to leave the stored secret unchanged. */
+  provider_client_secret: z.string().min(1).optional(),
+  scopes: z.array(providerScopeSchema).max(20).optional(),
+  profile_mapping: profileMappingSchema.optional(),
+  status: connectionStatusSchema.optional(),
+  /** design.md §20.3: the Dashboard owner's explicit confirmation step (only meaningful for `generic_oidc`; see `connectionSchema.owner_confirmed`). */
+  owner_confirmed: z.boolean().optional(),
+});
+export type ConnectionUpdateRequest = z.infer<typeof connectionUpdateRequestSchema>;
+
+export const connectionUpdateResponseSchema = connectionSchema;
+export type ConnectionUpdateResponse = z.infer<typeof connectionUpdateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// DELETE /connections/:connectionId
+// ---------------------------------------------------------------------------
+
+export const connectionDeleteResponseSchema = z.strictObject({
+  id: connectionIdSchema,
+  deleted: z.literal(true),
+});
+export type ConnectionDeleteResponse = z.infer<typeof connectionDeleteResponseSchema>;

package/src/domains.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from "vitest";
+import { canonicalizeCustomHostname, domainCreateRequestSchema, domainSchema } from "./domains.js";
+
+const VALID_DOMAIN = {
+  id: `dom_${"a".repeat(32)}`,
+  environment_id: `env_${"a".repeat(32)}`,
+  hostname: "login.customer.example",
+  status: "pending",
+  rp_enabled: true,
+  validation_errors: [],
+  created_at: "2026-08-02T08:10:00Z",
+  updated_at: "2026-08-02T08:10:00Z",
+  activated_at: null,
+};
+
+describe("domainSchema (design.md §11.9)", () => {
+  test("accepts a valid domain", () => {
+    expect(domainSchema.safeParse(VALID_DOMAIN).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking cloudflare_custom_hostname_id)", () => {
+    expect(
+      domainSchema.safeParse({ ...VALID_DOMAIN, cloudflare_custom_hostname_id: "ch_123" }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown status", () => {
+    expect(domainSchema.safeParse({ ...VALID_DOMAIN, status: "unknown" }).success).toBe(false);
+  });
+});
+
+describe("domainCreateRequestSchema", () => {
+  test("rp_enabled defaults to false", () => {
+    const parsed = domainCreateRequestSchema.parse({
+      environment_id: VALID_DOMAIN.environment_id,
+      hostname: "login.customer.example",
+    });
+    expect(parsed.rp_enabled).toBe(false);
+  });
+
+  test("canonicalizes hostnames explicitly at the boundary", () => {
+    const parsed = domainCreateRequestSchema.parse({
+      environment_id: VALID_DOMAIN.environment_id,
+      hostname: "LOGIN.Customer.Example",
+    });
+    expect(canonicalizeCustomHostname(parsed.hostname)).toBe("login.customer.example");
+  });
+});

package/src/domains.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { domainIdSchema, environmentIdSchema } from "./primitives.js";
+
+/**
+ * `custom_domains` (design.md §11.9, §8.2). `cloudflare_custom_hostname_id`
+ * is excluded: it is an internal pointer into the Cloudflare for SaaS API
+ * (the same "internal routing" category as the assignment's named
+ * `*_database_key`/`auth_partition_id` fields), not a customer-facing
+ * attribute — validation progress is fully described by `status` and
+ * `validation_errors` without it.
+ */
+export const CUSTOM_DOMAIN_STATUSES = ["pending", "active", "moved", "failed", "deleting"] as const;
+export const customDomainStatusSchema = z.enum(CUSTOM_DOMAIN_STATUSES);
+export type CustomDomainStatus = (typeof CUSTOM_DOMAIN_STATUSES)[number];
+
+const customHostnameSchema = z.string().min(1).max(253);
+
+/** Canonicalize a custom hostname at an external boundary before persistence or routing. */
+export const canonicalizeCustomHostname = (hostname: string): string => hostname.toLowerCase();
+
+export const domainSchema = z.strictObject({
+  id: domainIdSchema,
+  environment_id: environmentIdSchema,
+  hostname: customHostnameSchema,
+  status: customDomainStatusSchema,
+  /** design.md §11.9: whether this custom domain also serves as the WebAuthn RP ID host. */
+  rp_enabled: z.boolean(),
+  validation_errors: z.array(z.string().min(1)),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+  activated_at: z.iso.datetime().nullable(),
+});
+export type Domain = z.infer<typeof domainSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /domains
+// ---------------------------------------------------------------------------
+
+export const domainListQuerySchema = paginationQuerySchema.extend({
+  environment_id: environmentIdSchema,
+  status: customDomainStatusSchema.optional(),
+});
+export type DomainListQuery = z.infer<typeof domainListQuerySchema>;
+
+export const domainListResponseSchema = cursorPageSchema(domainSchema);
+export type DomainListResponse = z.infer<typeof domainListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /domains
+// ---------------------------------------------------------------------------
+export const domainCreateRequestSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  hostname: customHostnameSchema,
+  rp_enabled: z.boolean().default(false),
+});
+export type DomainCreateRequest = z.infer<typeof domainCreateRequestSchema>;
+
+/** A freshly created domain always starts `pending` validation (design.md §11.9). */
+export const domainCreateResponseSchema = domainSchema;
+export type DomainCreateResponse = z.infer<typeof domainCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /domains/:domainId
+// ---------------------------------------------------------------------------
+
+export const domainGetResponseSchema = domainSchema;
+export type DomainGetResponse = z.infer<typeof domainGetResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// DELETE /domains/:domainId
+// ---------------------------------------------------------------------------
+
+export const domainDeleteResponseSchema = z.strictObject({
+  id: domainIdSchema,
+  deleted: z.literal(true),
+});
+export type DomainDeleteResponse = z.infer<typeof domainDeleteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /domains/:domainId
+// ---------------------------------------------------------------------------
+/**
+ * design.md §8.3: `rp_enabled` switches both the WebAuthn RP ID and the hosted
+ * Interaction Domain to this custom domain. At most one per Environment.
+ */
+export const domainUpdateRequestSchema = z.strictObject({
+  rp_enabled: z.boolean(),
+});
+export type DomainUpdateRequest = z.infer<typeof domainUpdateRequestSchema>;
+
+export const domainUpdateResponseSchema = domainSchema;
+export type DomainUpdateResponse = z.infer<typeof domainUpdateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /domains/:domainId/retry-validation
+// ---------------------------------------------------------------------------
+
+export const domainRetryValidationRequestSchema = z.strictObject({});
+export type DomainRetryValidationRequest = z.infer<typeof domainRetryValidationRequestSchema>;
+
+/** Retrying resets `status` to `pending` and clears prior `validation_errors`. */
+export const domainRetryValidationResponseSchema = domainSchema;
+export type DomainRetryValidationResponse = z.infer<typeof domainRetryValidationResponseSchema>;

package/src/environments.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "vitest";
+import {
+  environmentCreateRequestSchema,
+  environmentSchema,
+  environmentUpdateRequestSchema,
+} from "./environments.js";
+
+const VALID_ENVIRONMENT = {
+  id: `env_${"a".repeat(32)}`,
+  project_id: `prj_${"a".repeat(32)}`,
+  type: "production",
+  name: "Production",
+  status: "active",
+  issuer: "https://id.example-auth.com/e/env_x",
+  interaction_domain: "env-x.login.example-auth.com",
+  rp_id: "env-x.login.example-auth.com",
+  config_version: 3,
+  created_at: "2026-08-02T08:10:00Z",
+  updated_at: "2026-08-02T08:10:00Z",
+};
+
+describe("environmentSchema (design.md §11.4)", () => {
+  test("accepts a valid environment", () => {
+    expect(environmentSchema.safeParse(VALID_ENVIRONMENT).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking auth_routing_version)", () => {
+    expect(
+      environmentSchema.safeParse({ ...VALID_ENVIRONMENT, auth_routing_version: 2 }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown type", () => {
+    expect(environmentSchema.safeParse({ ...VALID_ENVIRONMENT, type: "staging" }).success).toBe(
+      false,
+    );
+  });
+
+  test("issuer must be https", () => {
+    expect(
+      environmentSchema.safeParse({
+        ...VALID_ENVIRONMENT,
+        issuer: "http://id.example-auth.com/e/env_x",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("environmentCreateRequestSchema", () => {
+  test("does not accept a caller-supplied issuer/rp_id (server-derived, design.md §8)", () => {
+    expect(
+      environmentCreateRequestSchema.safeParse({
+        project_id: VALID_ENVIRONMENT.project_id,
+        type: "test",
+        name: "Test",
+        issuer: "https://attacker.example",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("environmentUpdateRequestSchema", () => {
+  test("cannot set status to deleted via PATCH (must use DELETE)", () => {
+    expect(environmentUpdateRequestSchema.safeParse({ status: "deleted" }).success).toBe(false);
+    expect(environmentUpdateRequestSchema.safeParse({ status: "suspended" }).success).toBe(true);
+  });
+});

package/src/environments.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { environmentIdSchema, httpsUrlSchema, projectIdSchema } from "./primitives.js";
+
+/**
+ * `environments` (design.md §11.4, §7.3). `auth_routing_version` is excluded
+ * as internal multi-cell routing state (design.md §10.6 `AuthLocatorDO`),
+ * the same category of field the assignment's "internal routing" exclusion
+ * targets alongside the explicitly named secret columns. `config_version` is
+ * kept: it is a plain monotonic counter for the environment's own config
+ * generation (design.md §11.4 `config_version INTEGER`), not a routing
+ * detail, and is useful for dashboard cache-busting.
+ */
+export const ENVIRONMENT_TYPES = ["test", "production"] as const;
+export const environmentTypeSchema = z.enum(ENVIRONMENT_TYPES);
+export type EnvironmentType = (typeof ENVIRONMENT_TYPES)[number];
+
+export const ENVIRONMENT_STATUSES = ["active", "suspended", "deleted"] as const;
+export const environmentStatusSchema = z.enum(ENVIRONMENT_STATUSES);
+export type EnvironmentStatus = (typeof ENVIRONMENT_STATUSES)[number];
+
+export const environmentSchema = z.strictObject({
+  id: environmentIdSchema,
+  project_id: projectIdSchema,
+  type: environmentTypeSchema,
+  name: z.string().min(1).max(200),
+  status: environmentStatusSchema,
+  /** design.md §8.1: the OIDC issuer URL, distinct from the interaction domain. */
+  issuer: httpsUrlSchema,
+  /** design.md §8.1: the Hosted Login / interaction-facing hostname. */
+  interaction_domain: z.string().min(1),
+  /** design.md §8.3, §17: WebAuthn Relying Party ID for this environment's passkeys. */
+  rp_id: z.string().min(1),
+  config_version: z.number().int().nonnegative(),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+});
+export type Environment = z.infer<typeof environmentSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /environments
+// ---------------------------------------------------------------------------
+
+export const environmentListQuerySchema = paginationQuerySchema.extend({
+  project_id: projectIdSchema,
+  type: environmentTypeSchema.optional(),
+});
+export type EnvironmentListQuery = z.infer<typeof environmentListQuerySchema>;
+
+export const environmentListResponseSchema = cursorPageSchema(environmentSchema);
+export type EnvironmentListResponse = z.infer<typeof environmentListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /environments
+// ---------------------------------------------------------------------------
+
+/**
+ * `issuer` / `interaction_domain` / `rp_id` are NOT client-settable at
+ * creation: they are server-derived from the new environment's id and the
+ * platform's root domain (design.md §8), then fixed for the environment's
+ * lifetime (design.md §7.3's isolation guarantees depend on this).
+ */
+export const environmentCreateRequestSchema = z.strictObject({
+  project_id: projectIdSchema,
+  type: environmentTypeSchema,
+  name: z.string().min(1).max(200),
+});
+export type EnvironmentCreateRequest = z.infer<typeof environmentCreateRequestSchema>;
+
+export const environmentCreateResponseSchema = environmentSchema;
+export type EnvironmentCreateResponse = z.infer<typeof environmentCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /environments/:environmentId
+// ---------------------------------------------------------------------------
+
+export const environmentGetResponseSchema = environmentSchema;
+export type EnvironmentGetResponse = z.infer<typeof environmentGetResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /environments/:environmentId
+// ---------------------------------------------------------------------------
+
+/** `status` here only toggles `active`/`suspended`; `deleted` is reached via `DELETE`, not `PATCH`. */
+export const environmentUpdateRequestSchema = z.strictObject({
+  name: z.string().min(1).max(200).optional(),
+  status: z.enum(["active", "suspended"]).optional(),
+});
+export type EnvironmentUpdateRequest = z.infer<typeof environmentUpdateRequestSchema>;
+
+export const environmentUpdateResponseSchema = environmentSchema;
+export type EnvironmentUpdateResponse = z.infer<typeof environmentUpdateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// DELETE /environments/:environmentId
+// ---------------------------------------------------------------------------
+
+export const environmentDeleteResponseSchema = z.strictObject({
+  id: environmentIdSchema,
+  status: z.literal("deleted"),
+});
+export type EnvironmentDeleteResponse = z.infer<typeof environmentDeleteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET  /environments/:environmentId/rp-migration
+// POST /environments/:environmentId/rp-migration/disable-legacy
+// ---------------------------------------------------------------------------
+
+/**
+ * RP ID migration progress (design.md §8.3). The migration is in effect while
+ * the Environment has an active `rp_enabled` custom domain: `active_rp_id` is
+ * that hostname and `legacy_rp_id` the Environment's original `rp_id`;
+ * otherwise `active_rp_id` = `rp_id` and `legacy_rp_id` = null.
+ * `legacy_disabled_at` is the stored value, returned even when not in effect.
+ * User counts cover every Auth partition and only non-revoked passkeys.
+ */
+export const rpMigrationResponseSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  active_rp_id: z.string(),
+  legacy_rp_id: z.string().nullable(),
+  legacy_disabled_at: z.iso.datetime().nullable(),
+  total_users: z.number().int().min(0),
+  migrated_users: z.number().int().min(0),
+  legacy_only_users: z.number().int().min(0),
+  migrated_share: z.number().min(0).max(1),
+});
+export type RpMigrationResponse = z.infer<typeof rpMigrationResponseSchema>;
+
+/** Irreversible: `confirm_rp_id` must equal the Environment's legacy `rp_id`. */
+export const rpMigrationDisableLegacyRequestSchema = z.strictObject({
+  confirm_rp_id: z.string().min(1),
+});
+export type RpMigrationDisableLegacyRequest = z.infer<typeof rpMigrationDisableLegacyRequestSchema>;