@smartcrab/contracts-management 0.1.0

package/src/audit-events.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema, requestIdSchema } from "./common.js";
+import { auditEventIdSchema, environmentIdSchema, workspaceIdSchema } from "./primitives.js";
+
+/**
+ * `audit_events` (design.md §12.11), read-only (`GET /audit-events` is the
+ * only route; design.md §12.11: "監査ログは追記専用とし、通常APIから更新・
+ * 削除できない"). `auth_partition_id` is excluded per the assignment's
+ * forbidden-field list (internal Auth D1 co-location routing).
+ * `ip_prefix_hash` is excluded for the same reason `@smartcrab/contracts-public`
+ * excludes hash-only columns from any response: an irreversible hash is not
+ * a usable value for an API consumer.
+ */
+export const AUDIT_ACTOR_TYPES = ["end_user", "workspace_member", "api_key", "system"] as const;
+export const auditActorTypeSchema = z.enum(AUDIT_ACTOR_TYPES);
+export type AuditActorType = (typeof AUDIT_ACTOR_TYPES)[number];
+
+export const AUDIT_RESULTS = ["success", "failure"] as const;
+export const auditResultSchema = z.enum(AUDIT_RESULTS);
+export type AuditResult = (typeof AUDIT_RESULTS)[number];
+
+const auditMetadataSchema = z.record(z.string(), z.unknown());
+
+export const auditEventSchema = z.strictObject({
+  id: auditEventIdSchema,
+  environment_id: environmentIdSchema,
+  workspace_id: workspaceIdSchema,
+  actor_type: auditActorTypeSchema,
+  actor_id: z.string().min(1).nullable(),
+  action: z.string().min(1),
+  subject_type: z.string().min(1),
+  subject_id: z.string().min(1).nullable(),
+  result: auditResultSchema,
+  request_id: requestIdSchema,
+  metadata: auditMetadataSchema,
+  created_at: z.iso.datetime(),
+});
+export type AuditEvent = z.infer<typeof auditEventSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /audit-events
+// ---------------------------------------------------------------------------
+
+export const auditEventListQuerySchema = paginationQuerySchema.extend({
+  environment_id: environmentIdSchema,
+  actor_type: auditActorTypeSchema.optional(),
+  action: z.string().min(1).optional(),
+  subject_type: z.string().min(1).optional(),
+  subject_id: z.string().min(1).optional(),
+  result: auditResultSchema.optional(),
+  created_after: z.iso.datetime().optional(),
+  created_before: z.iso.datetime().optional(),
+});
+export type AuditEventListQuery = z.infer<typeof auditEventListQuerySchema>;
+
+export const auditEventListResponseSchema = cursorPageSchema(auditEventSchema);
+export type AuditEventListResponse = z.infer<typeof auditEventListResponseSchema>;

package/src/billing.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "vitest";
+import {
+  billingCheckoutSessionCreateRequestSchema,
+  billingCheckoutSessionCreateResponseSchema,
+  billingPortalSessionCreateRequestSchema,
+  billingPortalSessionCreateResponseSchema,
+} from "./billing.js";
+
+describe("billing checkout-session (design.md §28.5)", () => {
+  test("request requires https success/cancel URLs", () => {
+    expect(
+      billingCheckoutSessionCreateRequestSchema.safeParse({
+        success_url: "https://dashboard.example.com/billing/success",
+        cancel_url: "https://dashboard.example.com/billing/cancel",
+      }).success,
+    ).toBe(true);
+    expect(
+      billingCheckoutSessionCreateRequestSchema.safeParse({
+        success_url: "http://dashboard.example.com/billing/success",
+        cancel_url: "https://dashboard.example.com/billing/cancel",
+      }).success,
+    ).toBe(false);
+  });
+
+  test("response only exposes a checkout URL, never a Stripe object id", () => {
+    const parsed = billingCheckoutSessionCreateResponseSchema.safeParse({
+      checkout_url: "https://checkout.stripe.com/c/pay/cs_test_abc",
+      expires_at: "2026-08-03T08:10:00Z",
+    });
+    expect(parsed.success).toBe(true);
+    expect(
+      billingCheckoutSessionCreateResponseSchema.safeParse({
+        checkout_url: "https://checkout.stripe.com/c/pay/cs_test_abc",
+        expires_at: "2026-08-03T08:10:00Z",
+        stripe_customer_id: "cus_123",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("billing portal-session", () => {
+  test("request requires an https return_url", () => {
+    expect(
+      billingPortalSessionCreateRequestSchema.safeParse({
+        return_url: "https://dashboard.example.com/billing",
+      }).success,
+    ).toBe(true);
+  });
+
+  test("response only exposes a portal URL", () => {
+    expect(
+      billingPortalSessionCreateResponseSchema.safeParse({
+        portal_url: "https://billing.stripe.com/session/abc",
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/billing.ts

@@ -0,0 +1,46 @@
+import { httpsUrlSchema } from "@smartcrab/contracts-public";
+import { z } from "zod";
+
+/**
+ * `POST /billing/checkout-session`, `POST /billing/portal-session`
+ * (design.md §26.2, §28.5: "30,000 MAUを超えて継続利用するにはStripe
+ * Customer、Subscription、Payment Methodを有効化する"). design.md does not
+ * give an exact JSON shape for these two routes; the request/response
+ * fields below are the minimum Stripe Checkout/Billing Portal session
+ * creation requires (a return destination in, a redirect URL out) and
+ * intentionally surface no Stripe object IDs — this package never exposes
+ * `billing_accounts`' Stripe identifiers (design.md §11.14) through these
+ * routes, only the redirect URL the dashboard needs.
+ */
+export const billingCheckoutSessionCreateRequestSchema = z.strictObject({
+  /** Where Stripe Checkout redirects on success. */
+  success_url: httpsUrlSchema,
+  /** Where Stripe Checkout redirects if the workspace member cancels. */
+  cancel_url: httpsUrlSchema,
+});
+export type BillingCheckoutSessionCreateRequest = z.infer<
+  typeof billingCheckoutSessionCreateRequestSchema
+>;
+
+export const billingCheckoutSessionCreateResponseSchema = z.strictObject({
+  checkout_url: httpsUrlSchema,
+  expires_at: z.iso.datetime(),
+});
+export type BillingCheckoutSessionCreateResponse = z.infer<
+  typeof billingCheckoutSessionCreateResponseSchema
+>;
+
+export const billingPortalSessionCreateRequestSchema = z.strictObject({
+  /** Where the Stripe Billing Portal redirects when the member is done. */
+  return_url: httpsUrlSchema,
+});
+export type BillingPortalSessionCreateRequest = z.infer<
+  typeof billingPortalSessionCreateRequestSchema
+>;
+
+export const billingPortalSessionCreateResponseSchema = z.strictObject({
+  portal_url: httpsUrlSchema,
+});
+export type BillingPortalSessionCreateResponse = z.infer<
+  typeof billingPortalSessionCreateResponseSchema
+>;

package/src/clients.test.ts

@@ -0,0 +1,169 @@
+import { describe, expect, test } from "vitest";
+import {
+  clientCreateRequestSchema,
+  clientCreateResponseSchema,
+  clientListResponseSchema,
+  clientSchema,
+  mobileAppSchema,
+} from "./clients.js";
+
+const VALID_CLIENT = {
+  id: `cli_${"a".repeat(32)}`,
+  environment_id: `env_${"a".repeat(32)}`,
+  client_type: "web_spa",
+  name: "Marketing site",
+  public_key_prefix: null,
+  redirect_uris: ["https://app.example.com/callback"],
+  post_logout_redirect_uris: ["https://app.example.com/"],
+  allowed_origins: ["https://app.example.com"],
+  allowed_scopes: ["openid", "profile", "email"],
+  allowed_resources: ["https://api.customer.example"],
+  token_endpoint_auth_method: "none",
+  require_pkce: true,
+  status: "active",
+  mobile_app: null,
+  created_at: "2026-08-02T08:10:00Z",
+  updated_at: "2026-08-02T08:10:00Z",
+};
+
+describe("clientSchema (design.md §11.5-§11.8, §7.4)", () => {
+  test("accepts a valid web_spa client", () => {
+    expect(clientSchema.safeParse(VALID_CLIENT).success).toBe(true);
+  });
+
+  test("accepts a react_native client with a mobile_app", () => {
+    const rnClient = {
+      ...VALID_CLIENT,
+      client_type: "react_native",
+      mobile_app: {
+        app_scheme: "com.customer.app",
+        ios_bundle_id: "com.customer.app",
+        ios_team_id: "ABCDE12345",
+        android_package_name: "com.customer.app",
+        android_sha256_fingerprints: [Array(32).fill("AA").join(":")],
+        universal_link_host: "app.customer.example",
+      },
+    };
+    expect(clientSchema.safeParse(rnClient).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key (e.g. leaking secret_hash)", () => {
+    expect(clientSchema.safeParse({ ...VALID_CLIENT, secret_hash: "abc" }).success).toBe(false);
+  });
+
+  test("rejects an origin carrying a path", () => {
+    expect(
+      clientSchema.safeParse({ ...VALID_CLIENT, allowed_origins: ["https://app.example.com/path"] })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("mobileAppSchema android fingerprints (design.md §11.8)", () => {
+  const VALID_APP = {
+    app_scheme: "com.customer.app",
+    ios_bundle_id: null,
+    ios_team_id: null,
+    android_package_name: "com.customer.app",
+    android_sha256_fingerprints: [] as string[],
+    universal_link_host: null,
+  };
+  const upper = Array(32).fill("AA").join(":");
+  const lower = Array(32).fill("aa").join(":");
+
+  test.each([
+    ["uppercase", upper],
+    ["lowercase", lower],
+  ])("accepts a %s colon-separated 32-byte fingerprint verbatim", (_label, fingerprint) => {
+    const parsed = mobileAppSchema.safeParse({
+      ...VALID_APP,
+      android_sha256_fingerprints: [fingerprint],
+    });
+    expect(parsed.success).toBe(true);
+    if (parsed.success) {
+      expect(parsed.data.android_sha256_fingerprints).toEqual([fingerprint]);
+    }
+  });
+
+  test.each([
+    ["no colons", "AA".repeat(32)],
+    ["31 pairs", Array(31).fill("AA").join(":")],
+    ["33 pairs", Array(33).fill("AA").join(":")],
+    ["non-hex", Array(32).fill("ZZ").join(":")],
+    ["truncated pair", `${Array(31).fill("AA").join(":")}:A`],
+  ])("rejects a fingerprint with %s", (_label, fingerprint) => {
+    expect(
+      mobileAppSchema.safeParse({ ...VALID_APP, android_sha256_fingerprints: [fingerprint] })
+        .success,
+    ).toBe(false);
+  });
+});
+
+describe("mobileAppSchema android_package_name (design.md §11.8)", () => {
+  const VALID_APP = {
+    app_scheme: "com.customer.app",
+    ios_bundle_id: null,
+    ios_team_id: null,
+    android_package_name: null as string | null,
+    android_sha256_fingerprints: [] as string[],
+    universal_link_host: null,
+  };
+
+  test("accepts a reversed-DNS package name and null", () => {
+    expect(
+      mobileAppSchema.safeParse({ ...VALID_APP, android_package_name: "com.example.app" }).success,
+    ).toBe(true);
+    expect(mobileAppSchema.safeParse(VALID_APP).success).toBe(true);
+  });
+
+  test.each([
+    ["single segment", "notreversedns"],
+    ["hyphen segment", "com.foo-bar"],
+    ["empty segment", "com..foo"],
+    ["leading digit", "1com.foo"],
+    ["empty string", ""],
+  ])("rejects a package name with %s", (_label, packageName) => {
+    expect(
+      mobileAppSchema.safeParse({ ...VALID_APP, android_package_name: packageName }).success,
+    ).toBe(false);
+  });
+});
+
+describe("clientCreateResponseSchema", () => {
+  test("may include a one-time client_secret for a confidential client", () => {
+    const parsed = clientCreateResponseSchema.safeParse({
+      ...VALID_CLIENT,
+      token_endpoint_auth_method: "client_secret_basic",
+      client_secret: "cs_live_abcdef123456",
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  test("client_secret is optional (e.g. a public client with auth method none)", () => {
+    expect(clientCreateResponseSchema.safeParse(VALID_CLIENT).success).toBe(true);
+  });
+});
+
+describe("clientListResponseSchema never includes a secret field per item", () => {
+  test("rejects an item carrying client_secret in the list envelope", () => {
+    expect(
+      clientListResponseSchema.safeParse({
+        items: [{ ...VALID_CLIENT, client_secret: "leaked" }],
+        next_cursor: null,
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("clientCreateRequestSchema", () => {
+  test("requires environment_id, client_type, name, token_endpoint_auth_method", () => {
+    expect(
+      clientCreateRequestSchema.safeParse({
+        environment_id: VALID_CLIENT.environment_id,
+        client_type: "web_bff",
+        name: "BFF",
+        token_endpoint_auth_method: "client_secret_basic",
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/clients.ts

@@ -0,0 +1,182 @@
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import { clientIdSchema, environmentIdSchema, httpsUrlSchema } from "./primitives.js";
+
+/**
+ * `clients` (design.md §11.5), `client_redirect_uris` (§11.6),
+ * `client_origins` (§11.7), `mobile_apps` (§11.8) and the conceptual Client
+ * model of design.md §7.4 (which groups these tables' columns into one
+ * resource: `redirect_uris`, `post_logout_redirect_uris`, `allowed_origins`,
+ * `allowed_scopes`, `allowed_resources`).
+ *
+ * `secret_hash` (§11.5) is excluded per the assignment's secret-field rule;
+ * `public_key_prefix` is kept — it exists specifically so a non-secret
+ * fragment of client identity can be displayed (the same pattern as
+ * `management_api_keys.prefix` alongside its hidden `key_mac`, §11.12).
+ */
+export const CLIENT_TYPES = ["web_bff", "web_spa", "react_native"] as const;
+export const clientTypeSchema = z.enum(CLIENT_TYPES);
+export type ClientType = (typeof CLIENT_TYPES)[number];
+
+export const TOKEN_ENDPOINT_AUTH_METHODS = [
+  "none",
+  "client_secret_basic",
+  "client_secret_post",
+] as const;
+export const tokenEndpointAuthMethodSchema = z.enum(TOKEN_ENDPOINT_AUTH_METHODS);
+export type TokenEndpointAuthMethod = (typeof TOKEN_ENDPOINT_AUTH_METHODS)[number];
+
+export const CLIENT_STATUSES = ["active", "disabled"] as const;
+export const clientStatusSchema = z.enum(CLIENT_STATUSES);
+export type ClientStatus = (typeof CLIENT_STATUSES)[number];
+
+/** design.md §11.6: exact-match only, no wildcards; §15.9 governs shape rules by client type. */
+const clientRedirectUriSchema = z.string().min(1).max(2048);
+
+/** design.md §11.7: "Originにはscheme、host、portのみを許可し、path/query/fragmentを拒否する。" */
+const originSchema = z.string().regex(/^https?:\/\/[^/?#]+$/);
+
+/** A single non-whitespace OAuth scope token, e.g. `openid` or a custom API scope. */
+const allowedScopeSchema = z.string().min(1).max(100).regex(/^\S+$/);
+
+/**
+ * design.md §11.8 `android_sha256_fingerprints_json`: colon-separated hex, 32
+ * bytes. Any case is accepted on the wire; the control-plane repository stores
+ * and serves the canonical uppercase form. Kept transform-free so the schema
+ * stays representable for OpenAPI generation (`z.toJSONSchema` with `io: "output"`).
+ */
+export const androidSha256FingerprintSchema = z
+  .string()
+  .regex(/^([0-9A-Fa-f]{2}:){31}[0-9A-Fa-f]{2}$/);
+
+/** design.md §11.8 `android_package_name`: reversed-DNS package name with at least two dot-separated segments. */
+export const androidPackageNameSchema = z
+  .string()
+  .regex(/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)+$/);
+
+/** design.md §11.8, §21.3, §27.3 "React Native設定": present only for `client_type: "react_native"`. */
+export const mobileAppSchema = z.strictObject({
+  app_scheme: z.string().min(1),
+  ios_bundle_id: z.string().min(1).nullable(),
+  ios_team_id: z.string().min(1).nullable(),
+  android_package_name: androidPackageNameSchema.nullable(),
+  android_sha256_fingerprints: z.array(androidSha256FingerprintSchema),
+  universal_link_host: z.string().min(1).nullable(),
+});
+export type MobileApp = z.infer<typeof mobileAppSchema>;
+
+export const clientSchema = z.strictObject({
+  id: clientIdSchema,
+  environment_id: environmentIdSchema,
+  client_type: clientTypeSchema,
+  name: z.string().min(1).max(200),
+  public_key_prefix: z.string().min(1).nullable(),
+  redirect_uris: z.array(clientRedirectUriSchema).max(50),
+  post_logout_redirect_uris: z.array(clientRedirectUriSchema).max(50),
+  allowed_origins: z.array(originSchema).max(50),
+  allowed_scopes: z.array(allowedScopeSchema).max(50),
+  allowed_resources: z.array(httpsUrlSchema).max(20),
+  token_endpoint_auth_method: tokenEndpointAuthMethodSchema,
+  require_pkce: z.boolean(),
+  status: clientStatusSchema,
+  mobile_app: mobileAppSchema.nullable(),
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+});
+export type Client = z.infer<typeof clientSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /clients
+// ---------------------------------------------------------------------------
+
+export const clientListQuerySchema = paginationQuerySchema.extend({
+  environment_id: environmentIdSchema,
+  client_type: clientTypeSchema.optional(),
+});
+export type ClientListQuery = z.infer<typeof clientListQuerySchema>;
+
+export const clientListResponseSchema = cursorPageSchema(clientSchema);
+export type ClientListResponse = z.infer<typeof clientListResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /clients
+// ---------------------------------------------------------------------------
+
+export const clientCreateRequestSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  client_type: clientTypeSchema,
+  name: z.string().min(1).max(200),
+  redirect_uris: z.array(clientRedirectUriSchema).max(50).default([]),
+  post_logout_redirect_uris: z.array(clientRedirectUriSchema).max(50).default([]),
+  allowed_origins: z.array(originSchema).max(50).default([]),
+  allowed_scopes: z.array(allowedScopeSchema).max(50).default([]),
+  allowed_resources: z.array(httpsUrlSchema).max(20).default([]),
+  token_endpoint_auth_method: tokenEndpointAuthMethodSchema,
+  require_pkce: z.boolean().default(true),
+  mobile_app: mobileAppSchema.optional(),
+});
+export type ClientCreateRequest = z.infer<typeof clientCreateRequestSchema>;
+
+/**
+ * design.md §11.12's "Secretは作成時に1回だけ表示する" applies by the same
+ * logic to any generated confidential-client secret: `client_secret` is
+ * present only when `token_endpoint_auth_method !== "none"`, and only on this
+ * one response — never on `GET`/`PATCH`/list.
+ */
+export const clientCreateResponseSchema = clientSchema.extend({
+  client_secret: z.string().min(1).optional(),
+});
+export type ClientCreateResponse = z.infer<typeof clientCreateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /clients/:clientId
+// ---------------------------------------------------------------------------
+
+export const clientGetResponseSchema = clientSchema;
+export type ClientGetResponse = z.infer<typeof clientGetResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// PATCH /clients/:clientId
+// ---------------------------------------------------------------------------
+
+export const clientUpdateRequestSchema = z.strictObject({
+  name: z.string().min(1).max(200).optional(),
+  redirect_uris: z.array(clientRedirectUriSchema).max(50).optional(),
+  post_logout_redirect_uris: z.array(clientRedirectUriSchema).max(50).optional(),
+  allowed_origins: z.array(originSchema).max(50).optional(),
+  allowed_scopes: z.array(allowedScopeSchema).max(50).optional(),
+  allowed_resources: z.array(httpsUrlSchema).max(20).optional(),
+  token_endpoint_auth_method: tokenEndpointAuthMethodSchema.optional(),
+  require_pkce: z.boolean().optional(),
+  status: clientStatusSchema.optional(),
+  mobile_app: mobileAppSchema.nullable().optional(),
+});
+export type ClientUpdateRequest = z.infer<typeof clientUpdateRequestSchema>;
+
+export const clientUpdateResponseSchema = clientSchema;
+export type ClientUpdateResponse = z.infer<typeof clientUpdateResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// DELETE /clients/:clientId
+// ---------------------------------------------------------------------------
+
+export const clientDeleteResponseSchema = z.strictObject({
+  id: clientIdSchema,
+  deleted: z.literal(true),
+});
+export type ClientDeleteResponse = z.infer<typeof clientDeleteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /clients/:clientId/rotate-secret
+// ---------------------------------------------------------------------------
+
+export const clientRotateSecretRequestSchema = z.strictObject({});
+export type ClientRotateSecretRequest = z.infer<typeof clientRotateSecretRequestSchema>;
+
+/** One-time plaintext secret (design.md §11.12's display-once rule, applied to client secrets). */
+export const clientRotateSecretResponseSchema = z.strictObject({
+  id: clientIdSchema,
+  client_secret: z.string().min(1),
+  rotated_at: z.iso.datetime(),
+});
+export type ClientRotateSecretResponse = z.infer<typeof clientRotateSecretResponseSchema>;

package/src/common.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "vitest";
+import {
+  cursorPageSchema,
+  idempotencyKeyHeaderSchema,
+  ifMatchHeaderSchema,
+  paginationQuerySchema,
+  problemDetailsSchema,
+  requestIdHeaderSchema,
+} from "./common.js";
+import { z } from "zod";
+
+describe("paginationQuerySchema (design.md §26.3)", () => {
+  test("defaults limit to 25 when omitted", () => {
+    const parsed = paginationQuerySchema.parse({});
+    expect(parsed.limit).toBe(25);
+    expect(parsed.cursor).toBeUndefined();
+  });
+
+  test("accepts a cursor and an in-range limit", () => {
+    const parsed = paginationQuerySchema.parse({ cursor: "abc", limit: "50" });
+    expect(parsed).toEqual({ cursor: "abc", limit: 50 });
+  });
+
+  test("rejects a limit above the max page size of 100", () => {
+    expect(paginationQuerySchema.safeParse({ limit: 101 }).success).toBe(false);
+    expect(paginationQuerySchema.safeParse({ limit: 100 }).success).toBe(true);
+  });
+
+  test("rejects a non-positive limit", () => {
+    expect(paginationQuerySchema.safeParse({ limit: 0 }).success).toBe(false);
+  });
+});
+
+describe("cursorPageSchema", () => {
+  const itemSchema = z.strictObject({ name: z.string() });
+  const pageSchema = cursorPageSchema(itemSchema);
+
+  test("accepts items plus a nullable next_cursor", () => {
+    expect(pageSchema.safeParse({ items: [{ name: "a" }], next_cursor: null }).success).toBe(true);
+    expect(pageSchema.safeParse({ items: [], next_cursor: "cur_abc" }).success).toBe(true);
+  });
+
+  test("rejects an unknown top-level key", () => {
+    expect(pageSchema.safeParse({ items: [], next_cursor: null, total: 1 }).success).toBe(false);
+  });
+
+  test("rejects a missing next_cursor", () => {
+    expect(pageSchema.safeParse({ items: [] }).success).toBe(false);
+  });
+});
+
+describe("idempotencyKeyHeaderSchema / ifMatchHeaderSchema (design.md §26.3)", () => {
+  test("idempotency key header requires a non-empty value", () => {
+    expect(idempotencyKeyHeaderSchema.safeParse({ "idempotency-key": "key-123" }).success).toBe(
+      true,
+    );
+    expect(idempotencyKeyHeaderSchema.safeParse({ "idempotency-key": "" }).success).toBe(false);
+  });
+
+  test("if-match header requires a non-empty ETag value", () => {
+    expect(ifMatchHeaderSchema.safeParse({ "if-match": '"v1"' }).success).toBe(true);
+    expect(ifMatchHeaderSchema.safeParse({ "if-match": "" }).success).toBe(false);
+  });
+});
+
+describe("requestIdHeaderSchema", () => {
+  test("requires the req_ prefix and 32 base32url chars", () => {
+    expect(
+      requestIdHeaderSchema.safeParse({ "x-request-id": `req_${"a".repeat(32)}` }).success,
+    ).toBe(true);
+    expect(requestIdHeaderSchema.safeParse({ "x-request-id": "req_short" }).success).toBe(false);
+  });
+});
+
+describe("problemDetailsSchema (design.md §26.3 example)", () => {
+  test("accepts the exact example from design.md", () => {
+    const parsed = problemDetailsSchema.safeParse({
+      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_${"a".repeat(32)}`,
+    });
+    expect(parsed.success).toBe(true);
+  });
+
+  test("allows RFC 9457 extension members alongside the standard fields", () => {
+    expect(
+      problemDetailsSchema.safeParse({
+        type: "https://docs.example-auth.com/errors/conflict",
+        title: "Conflict",
+        status: 409,
+        current_etag: '"v2"',
+      }).success,
+    ).toBe(true);
+  });
+
+  test("requires type/title/status", () => {
+    expect(problemDetailsSchema.safeParse({ title: "x", status: 400 }).success).toBe(false);
+  });
+});