@smartcrab/contracts-management 0.1.0

package/src/secret-fields.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import * as contracts from "./index.js";
+
+/**
+ * design.md §2.6/§16.2 (and this package's assignment notes): the
+ * Management API must never expose secret ciphertext/MAC columns or
+ * internal cross-shard routing identifiers. This test enumerates every
+ * exported zod schema in the package's public surface and asserts none of
+ * them can ever produce a field with one of these names, at any nesting
+ * depth (list item, nested object, record value, etc).
+ */
+const FORBIDDEN_FIELD_NAMES = [
+  "secret_ciphertext",
+  "secret_iv",
+  "key_mac",
+  "encrypted_private_jwk",
+  "control_database_key",
+  "auth_database_key",
+  "auth_partition_id",
+  "email_ciphertext",
+  "token_mac",
+] as const;
+
+/**
+ * Walks a JSON Schema document (as produced by `z.toJSONSchema`, per this
+ * repo's IMPL_NOTES.md §6 convention) and collects every field name that
+ * appears as an object's `properties` key, at any depth. This avoids
+ * reaching into zod's internal schema representation: `z.toJSONSchema` is
+ * the documented, stable way to introspect a schema's shape.
+ */
+const collectFieldNames = (value: unknown, into: Set<string>): void => {
+  if (Array.isArray(value)) {
+    for (const item of value) collectFieldNames(item, into);
+    return;
+  }
+  if (typeof value !== "object" || value === null) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (
+      key === "properties" &&
+      typeof child === "object" &&
+      child !== null &&
+      !Array.isArray(child)
+    ) {
+      for (const fieldName of Object.keys(child)) into.add(fieldName);
+    }
+    collectFieldNames(child, into);
+  }
+};
+
+const exportedSchemas: ReadonlyArray<readonly [string, z.ZodType]> = Object.entries(
+  contracts,
+).flatMap(([name, value]) => (value instanceof z.ZodType ? [[name, value] as const] : []));
+
+describe("no exported schema ever exposes a forbidden secret/internal-routing field", () => {
+  test("at least one zod schema was actually collected (sanity check for the introspection itself)", () => {
+    expect(exportedSchemas.length).toBeGreaterThan(20);
+  });
+
+  for (const [name, schema] of exportedSchemas) {
+    test(`${name} does not contain any forbidden field name`, () => {
+      const fieldNames = new Set<string>();
+      collectFieldNames(z.toJSONSchema(schema), fieldNames);
+      const offenders = FORBIDDEN_FIELD_NAMES.filter((forbidden) => fieldNames.has(forbidden));
+      expect(offenders).toEqual([]);
+    });
+  }
+});
+
+describe("forbidden-field detection actually works (negative control)", () => {
+  test("collectFieldNames finds a forbidden field name when one is present", () => {
+    const canary = z.object({ id: z.string(), secret_ciphertext: z.string() });
+    const fieldNames = new Set<string>();
+    collectFieldNames(z.toJSONSchema(canary), fieldNames);
+    expect(fieldNames.has("secret_ciphertext")).toBe(true);
+  });
+
+  test("collectFieldNames finds a forbidden field name nested inside an array item", () => {
+    const canary = z.object({ items: z.array(z.object({ auth_partition_id: z.string() })) });
+    const fieldNames = new Set<string>();
+    collectFieldNames(z.toJSONSchema(canary), fieldNames);
+    expect(fieldNames.has("auth_partition_id")).toBe(true);
+  });
+});

package/src/usage.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "vitest";
+import { MAU_FREE_TIER_LIMIT, mauUsageResponseSchema } from "./usage.js";
+
+const VALID_USAGE = {
+  workspace_id: `wsp_${"a".repeat(32)}`,
+  billing_month: "2026-08",
+  total_count: 28_500,
+  free_tier_limit: MAU_FREE_TIER_LIMIT,
+  percent_used: 95,
+  threshold_reached: 95,
+  billing_activated: false,
+  grace_period: {
+    status: "none",
+    started_at: null,
+    expires_at: null,
+    new_user_creation_blocked: false,
+  },
+  environments: [{ environment_id: `env_${"a".repeat(32)}`, count: 28_500 }],
+};
+
+describe("mauUsageResponseSchema (design.md §28)", () => {
+  test("accepts a valid usage response", () => {
+    expect(mauUsageResponseSchema.safeParse(VALID_USAGE).success).toBe(true);
+  });
+
+  test("free_tier_limit is fixed at 30,000 (design.md §28.3)", () => {
+    expect(
+      mauUsageResponseSchema.safeParse({ ...VALID_USAGE, free_tier_limit: 50_000 }).success,
+    ).toBe(false);
+  });
+
+  test("rejects an unknown threshold level", () => {
+    expect(
+      mauUsageResponseSchema.safeParse({ ...VALID_USAGE, threshold_reached: 50 }).success,
+    ).toBe(false);
+  });
+
+  test("accepts an active grace period (design.md §28.5)", () => {
+    expect(
+      mauUsageResponseSchema.safeParse({
+        ...VALID_USAGE,
+        grace_period: {
+          status: "active",
+          started_at: "2026-08-01T00:00:00Z",
+          expires_at: "2026-08-04T00:00:00Z",
+          new_user_creation_blocked: false,
+        },
+      }).success,
+    ).toBe(true);
+  });
+
+  test("rejects an unknown top-level key", () => {
+    expect(
+      mauUsageResponseSchema.safeParse({ ...VALID_USAGE, control_database_key: "x" }).success,
+    ).toBe(false);
+  });
+});

package/src/usage.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { environmentIdSchema, workspaceIdSchema } from "./primitives.js";
+
+/**
+ * `GET /usage/mau` (design.md §28: MAU課金). No D1 table is projected 1:1
+ * here — `mau_month` (§12.10) is a per-user ledger row, while this route
+ * reports the aggregated-per-workspace view design.md §28.5 describes:
+ * the free tier limit, threshold notifications, and grace period state.
+ */
+export const MAU_FREE_TIER_LIMIT = 30_000;
+
+/** design.md §28.5: "80%、95%、100%到達時にOwner/Billing roleへ通知". */
+export const MAU_THRESHOLD_LEVELS = [80, 95, 100] as const;
+export const mauThresholdLevelSchema = z.union([z.literal(80), z.literal(95), z.literal(100)]);
+export type MauThresholdLevel = (typeof MAU_THRESHOLD_LEVELS)[number];
+
+/** `billing_month` wire format: `YYYY-MM` (design.md §12.10 `mau_month.billing_month`). */
+export const billingMonthSchema = z.string().regex(/^\d{4}-(?:0[1-9]|1[0-2])$/);
+
+/**
+ * design.md §28.5: unbilled workspaces get a 72-hour grace period at 30,000
+ * MAU; existing users keep logging in throughout, but if billing is not
+ * activated before it expires, only new-user creation is blocked.
+ */
+export const GRACE_PERIOD_STATUSES = ["none", "active", "expired"] as const;
+export const gracePeriodStatusSchema = z.enum(GRACE_PERIOD_STATUSES);
+export type GracePeriodStatus = (typeof GRACE_PERIOD_STATUSES)[number];
+
+export const gracePeriodSchema = z.strictObject({
+  status: gracePeriodStatusSchema,
+  started_at: z.iso.datetime().nullable(),
+  /** design.md §28.5: "72時間のgrace period". */
+  expires_at: z.iso.datetime().nullable(),
+  /** design.md §28.5: "新規ユーザー作成だけを停止する" once the grace period lapses unbilled. */
+  new_user_creation_blocked: z.boolean(),
+});
+export type GracePeriod = z.infer<typeof gracePeriodSchema>;
+
+const mauEnvironmentBreakdownSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  count: z.number().int().nonnegative(),
+});
+export type MauEnvironmentBreakdown = z.infer<typeof mauEnvironmentBreakdownSchema>;
+
+export const mauUsageResponseSchema = z.strictObject({
+  workspace_id: workspaceIdSchema,
+  billing_month: billingMonthSchema,
+  total_count: z.number().int().nonnegative(),
+  free_tier_limit: z.literal(MAU_FREE_TIER_LIMIT),
+  percent_used: z.number().nonnegative(),
+  /** Highest threshold level reached so far this billing month, or `null` if none. */
+  threshold_reached: mauThresholdLevelSchema.nullable(),
+  /** design.md §28.5: whether Stripe Customer/Subscription/Payment Method are active. */
+  billing_activated: z.boolean(),
+  grace_period: gracePeriodSchema,
+  environments: z.array(mauEnvironmentBreakdownSchema),
+});
+export type MauUsageResponse = z.infer<typeof mauUsageResponseSchema>;
+
+export const mauUsageQuerySchema = z.object({
+  /** Defaults server-side to the current billing month when omitted. */
+  billing_month: billingMonthSchema.optional(),
+  /** Narrows `environments` to a single environment (the top-level totals still reflect the whole workspace). */
+  environment_id: environmentIdSchema.optional(),
+});
+export type MauUsageQuery = z.infer<typeof mauUsageQuerySchema>;

package/src/user-jobs.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from "vitest";
+import {
+  userExportJobCreateRequestSchema,
+  userExportJobSchema,
+  userImportJobCreateRequestSchema,
+  userImportJobSchema,
+} from "./user-jobs.js";
+
+const ENVIRONMENT_ID = `env_${"a".repeat(32)}`;
+
+describe("userImportJobSchema", () => {
+  test("accepts a valid job", () => {
+    expect(
+      userImportJobSchema.safeParse({
+        id: `job_${"a".repeat(32)}`,
+        environment_id: ENVIRONMENT_ID,
+        status: "processing",
+        format: "csv",
+        source_url: "https://uploads.example.com/import.csv",
+        total_records: 100,
+        processed_records: 40,
+        succeeded_records: 38,
+        failed_records: 2,
+        error_report_url: null,
+        created_by: { actor_type: "workspace_member", actor_id: `usr_${"a".repeat(32)}` },
+        created_at: "2026-08-02T08:10:00Z",
+        updated_at: "2026-08-02T08:10:00Z",
+        completed_at: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  test("rejects an unknown top-level key", () => {
+    expect(
+      userImportJobCreateRequestSchema.safeParse({
+        environment_id: ENVIRONMENT_ID,
+        format: "json",
+        source_url: "https://uploads.example.com/import.json",
+        records: [{ email: "a@b.com" }],
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("userExportJobSchema (design.md §33.3)", () => {
+  const validExportJob = {
+    id: `job_${"a".repeat(32)}`,
+    environment_id: ENVIRONMENT_ID,
+    target_user_id: `usr_${"a".repeat(32)}`,
+    status: "completed",
+    contents: [
+      "profile",
+      "emails",
+      "linked_identities",
+      "passkey_metadata",
+      "sessions",
+      "consent",
+      "audit_events",
+    ],
+    download_url: "https://exports.example.com/user-export.json",
+    download_url_expires_at: "2026-08-03T08:10:00Z",
+    created_by: { actor_type: "api_key", actor_id: `mky_${"a".repeat(32)}` },
+    created_at: "2026-08-02T08:10:00Z",
+    updated_at: "2026-08-02T08:10:00Z",
+    completed_at: "2026-08-02T08:15:00Z",
+  };
+
+  test("accepts a valid export job with the full §33.3 content list", () => {
+    expect(userExportJobSchema.safeParse(validExportJob).success).toBe(true);
+  });
+
+  test("rejects a content value not in design.md §33.3's list (e.g. a private key)", () => {
+    expect(
+      userExportJobSchema.safeParse({ ...validExportJob, contents: ["private_key"] }).success,
+    ).toBe(false);
+  });
+
+  test("create request only needs environment_id and target_user_id", () => {
+    expect(
+      userExportJobCreateRequestSchema.safeParse({
+        environment_id: ENVIRONMENT_ID,
+        target_user_id: validExportJob.target_user_id,
+      }).success,
+    ).toBe(true);
+  });
+});

package/src/user-jobs.ts

@@ -0,0 +1,120 @@
+import { httpsUrlSchema } from "@smartcrab/contracts-public";
+import { z } from "zod";
+import { environmentIdSchema, jobIdSchema, userIdSchema } from "./primitives.js";
+
+/**
+ * `user-import-jobs` / `user-export-jobs` (design.md §26.2 route list).
+ *
+ * DEVIATION: design.md §11/§12 do not define a D1 table for either job kind
+ * (unlike every other resource in this package, whose field set is a direct
+ * projection of a named table). The shape below is derived from:
+ * - design.md §33.3 ("Export"): the fixed list of data an export contains
+ *   (profile, emails, linked identities, passkey metadata, sessions,
+ *   consent, the user's own audit events) and its explicit exclusion list
+ *   (private key, provider token, internal risk score).
+ * - the async job lifecycle convention used elsewhere in the schema, e.g.
+ *   `email_deliveries.status` (§12.8) and `outbox_events.status` (§11.16).
+ * - design.md §14.0's "1 row/valueは64 KB以下" (rows/values capped at 64 KB) —
+ *   bulk import records and export output are therefore referenced by an R2
+ *   URL, never embedded inline in the job resource itself.
+ *
+ * Should a future design.md revision add explicit
+ * `user_import_jobs`/`user_export_jobs` tables, this file's field set should
+ * be reconciled against them.
+ */
+export const JOB_STATUSES = ["pending", "processing", "completed", "failed"] as const;
+export const jobStatusSchema = z.enum(JOB_STATUSES);
+export type JobStatus = (typeof JOB_STATUSES)[number];
+
+/** Who requested the job (design.md §12.11 `audit_events.actor_type` narrowed to the kinds that can trigger a job). */
+const JOB_ACTOR_TYPES = ["workspace_member", "api_key"] as const;
+const jobActorSchema = z.strictObject({
+  actor_type: z.enum(JOB_ACTOR_TYPES),
+  actor_id: z.string().min(1),
+});
+
+// ---------------------------------------------------------------------------
+// POST /user-import-jobs, GET /user-import-jobs/:jobId
+// ---------------------------------------------------------------------------
+
+export const USER_IMPORT_FORMATS = ["json", "csv"] as const;
+export const userImportFormatSchema = z.enum(USER_IMPORT_FORMATS);
+export type UserImportFormat = (typeof USER_IMPORT_FORMATS)[number];
+
+export const userImportJobSchema = z.strictObject({
+  id: jobIdSchema,
+  environment_id: environmentIdSchema,
+  status: jobStatusSchema,
+  format: userImportFormatSchema,
+  /** Where the platform fetched the source records from (an R2/customer-hosted HTTPS URL). */
+  source_url: httpsUrlSchema,
+  total_records: z.number().int().nonnegative().nullable(),
+  processed_records: z.number().int().nonnegative(),
+  succeeded_records: z.number().int().nonnegative(),
+  failed_records: z.number().int().nonnegative(),
+  /** Present once the job has processed at least one failing record; an R2-hosted per-row error report. */
+  error_report_url: httpsUrlSchema.nullable(),
+  created_by: jobActorSchema,
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+  completed_at: z.iso.datetime().nullable(),
+});
+export type UserImportJob = z.infer<typeof userImportJobSchema>;
+
+export const userImportJobCreateRequestSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  format: userImportFormatSchema,
+  source_url: httpsUrlSchema,
+});
+export type UserImportJobCreateRequest = z.infer<typeof userImportJobCreateRequestSchema>;
+
+export const userImportJobCreateResponseSchema = userImportJobSchema;
+export type UserImportJobCreateResponse = z.infer<typeof userImportJobCreateResponseSchema>;
+
+export const userImportJobGetResponseSchema = userImportJobSchema;
+export type UserImportJobGetResponse = z.infer<typeof userImportJobGetResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// POST /user-export-jobs, GET /user-export-jobs/:jobId
+// ---------------------------------------------------------------------------
+
+/** design.md §33.3's fixed export content list; not caller-configurable. */
+export const USER_EXPORT_CONTENTS = [
+  "profile",
+  "emails",
+  "linked_identities",
+  "passkey_metadata",
+  "sessions",
+  "consent",
+  "audit_events",
+] as const;
+export const userExportContentSchema = z.enum(USER_EXPORT_CONTENTS);
+export type UserExportContent = (typeof USER_EXPORT_CONTENTS)[number];
+
+export const userExportJobSchema = z.strictObject({
+  id: jobIdSchema,
+  environment_id: environmentIdSchema,
+  target_user_id: userIdSchema,
+  status: jobStatusSchema,
+  contents: z.array(userExportContentSchema),
+  /** Present once `status: "completed"`: a time-limited presigned R2 URL for the JSON export. */
+  download_url: httpsUrlSchema.nullable(),
+  download_url_expires_at: z.iso.datetime().nullable(),
+  created_by: jobActorSchema,
+  created_at: z.iso.datetime(),
+  updated_at: z.iso.datetime(),
+  completed_at: z.iso.datetime().nullable(),
+});
+export type UserExportJob = z.infer<typeof userExportJobSchema>;
+
+export const userExportJobCreateRequestSchema = z.strictObject({
+  environment_id: environmentIdSchema,
+  target_user_id: userIdSchema,
+});
+export type UserExportJobCreateRequest = z.infer<typeof userExportJobCreateRequestSchema>;
+
+export const userExportJobCreateResponseSchema = userExportJobSchema;
+export type UserExportJobCreateResponse = z.infer<typeof userExportJobCreateResponseSchema>;
+
+export const userExportJobGetResponseSchema = userExportJobSchema;
+export type UserExportJobGetResponse = z.infer<typeof userExportJobGetResponseSchema>;

package/src/user-subresources.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from "vitest";
+import {
+  userIdentityListQuerySchema,
+  userIdentityListResponseSchema,
+  userIdentitySchema,
+  userPasskeyListQuerySchema,
+  userPasskeySchema,
+  userSessionListQuerySchema,
+  userSessionSchema,
+  userSessionsRevokeAllResponseSchema,
+} from "./user-subresources.js";
+
+const USER_ID = `usr_${"a".repeat(32)}`;
+
+describe("userIdentitySchema (design.md §12.3)", () => {
+  test("accepts a valid identity", () => {
+    expect(
+      userIdentitySchema.safeParse({
+        identity_id: `idn_${"a".repeat(32)}`,
+        user_id: USER_ID,
+        provider: "google",
+        linked_at: "2026-08-02T08:10:00Z",
+        last_used_at: null,
+      }).success,
+    ).toBe(true);
+  });
+
+  test("rejects provider_subject/profile_json/token ciphertext leaking through", () => {
+    expect(
+      userIdentitySchema.safeParse({
+        identity_id: `idn_${"a".repeat(32)}`,
+        user_id: USER_ID,
+        provider: "google",
+        linked_at: "2026-08-02T08:10:00Z",
+        last_used_at: null,
+        access_token_ciphertext: "abc",
+      }).success,
+    ).toBe(false);
+  });
+});
+
+describe("userPasskeySchema (design.md §12.5)", () => {
+  test("rejects credential_id/public_key/sign_count leaking through", () => {
+    const base = {
+      passkey_id: `psk_${"a".repeat(32)}`,
+      user_id: USER_ID,
+      name: "iPhone 15",
+      created_at: "2026-08-02T08:10:00Z",
+      last_used_at: null,
+      device_type: "multi_device",
+      backed_up: true,
+    };
+    expect(userPasskeySchema.safeParse(base).success).toBe(true);
+    expect(userPasskeySchema.safeParse({ ...base, sign_count: 4 }).success).toBe(false);
+    expect(userPasskeySchema.safeParse({ ...base, public_key: "abc" }).success).toBe(false);
+  });
+});
+
+describe("userSessionSchema (design.md §12.4)", () => {
+  test("rejects token_mac leaking through", () => {
+    const base = {
+      session_id: `ses_${"a".repeat(32)}`,
+      user_id: USER_ID,
+      client_id: `cli_${"a".repeat(32)}`,
+      device_name: null,
+      created_at: "2026-08-02T08:10:00Z",
+      last_active_at: "2026-08-02T08:10:00Z",
+      idle_expires_at: "2026-08-02T09:10:00Z",
+      absolute_expires_at: "2026-08-09T08:10:00Z",
+      revoked_at: null,
+    };
+    expect(userSessionSchema.safeParse(base).success).toBe(true);
+    expect(userSessionSchema.safeParse({ ...base, token_mac: "abc" }).success).toBe(false);
+  });
+});
+
+describe("userIdentityListResponseSchema pagination envelope", () => {
+  test("wraps identities in a cursor page", () => {
+    expect(
+      userIdentityListResponseSchema.safeParse({
+        items: [
+          {
+            identity_id: `idn_${"a".repeat(32)}`,
+            user_id: USER_ID,
+            provider: "apple",
+            linked_at: "2026-08-02T08:10:00Z",
+            last_used_at: null,
+          },
+        ],
+        next_cursor: null,
+      }).success,
+    ).toBe(true);
+  });
+});
+
+describe("user sub-resource query schemas", () => {
+  test("require environment_id for every list route", () => {
+    const environment_id = `env_${"a".repeat(32)}`;
+    for (const schema of [
+      userIdentityListQuerySchema,
+      userPasskeyListQuerySchema,
+      userSessionListQuerySchema,
+    ]) {
+      expect(schema.safeParse({ environment_id }).success).toBe(true);
+      expect(schema.safeParse({}).success).toBe(false);
+    }
+  });
+});
+
+describe("userSessionsRevokeAllResponseSchema", () => {
+  test("only reports revoked: true", () => {
+    expect(userSessionsRevokeAllResponseSchema.safeParse({ revoked: true }).success).toBe(true);
+    expect(userSessionsRevokeAllResponseSchema.safeParse({ revoked: false }).success).toBe(false);
+  });
+});

package/src/user-subresources.ts

@@ -0,0 +1,128 @@
+import { socialProviderSchema } from "@smartcrab/contracts-public";
+import { z } from "zod";
+import { cursorPageSchema, paginationQuerySchema } from "./common.js";
+import {
+  clientIdSchema,
+  environmentIdSchema,
+  identityIdSchema,
+  passkeyIdSchema,
+  sessionIdSchema,
+  userIdSchema,
+} from "./primitives.js";
+
+/**
+ * Admin-facing projections of a user's sub-resources: `identities` (design.md
+ * §12.3), `passkeys` (§12.5), `sessions` (§12.4). Same exclusions as
+ * `@smartcrab/contracts-public`'s `/v1/me` sub-resource schemas
+ * (`provider_subject`, `profile_json`, token ciphertexts, `credential_id`,
+ * `public_key`, `sign_count`, `token_mac` (assignment's forbidden list),
+ * `ip_prefix_hash`/`user_agent_hash`), plus `user_id` added back in since
+ * these admin routes are not scoped to "the current session's own user" the
+ * way `/v1/me` is.
+ */
+
+/** Environment context required by every user sub-resource route. */
+export const userSubresourceQuerySchema = z.strictObject({
+  environment_id: environmentIdSchema,
+});
+export type UserSubresourceQuery = z.infer<typeof userSubresourceQuerySchema>;
+
+const userSubresourceListQuerySchema = paginationQuerySchema.extend({
+  environment_id: environmentIdSchema,
+});
+
+// ---------------------------------------------------------------------------
+// GET /users/:userId/identities, DELETE /users/:userId/identities/:identityId
+// ---------------------------------------------------------------------------
+
+export const userIdentitySchema = z.strictObject({
+  identity_id: identityIdSchema,
+  user_id: userIdSchema,
+  provider: socialProviderSchema,
+  linked_at: z.iso.datetime(),
+  last_used_at: z.iso.datetime().nullable(),
+});
+export type UserIdentity = z.infer<typeof userIdentitySchema>;
+
+export const userIdentityListQuerySchema = userSubresourceListQuerySchema;
+export type UserIdentityListQuery = z.infer<typeof userIdentityListQuerySchema>;
+
+export const userIdentityListResponseSchema = cursorPageSchema(userIdentitySchema);
+export type UserIdentityListResponse = z.infer<typeof userIdentityListResponseSchema>;
+
+export const userIdentityDeleteResponseSchema = z.strictObject({
+  identity_id: identityIdSchema,
+  deleted: z.literal(true),
+});
+export type UserIdentityDeleteResponse = z.infer<typeof userIdentityDeleteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /users/:userId/passkeys, DELETE /users/:userId/passkeys/:passkeyId
+// ---------------------------------------------------------------------------
+
+const AUTHENTICATOR_TRANSPORTS = ["ble", "hybrid", "internal", "nfc", "usb"] as const;
+const authenticatorTransportSchema = z.enum(AUTHENTICATOR_TRANSPORTS);
+
+export const PASSKEY_DEVICE_TYPES = ["single_device", "multi_device"] as const;
+export const passkeyDeviceTypeSchema = z.enum(PASSKEY_DEVICE_TYPES);
+export type PasskeyDeviceType = (typeof PASSKEY_DEVICE_TYPES)[number];
+
+export const userPasskeySchema = z.strictObject({
+  passkey_id: passkeyIdSchema,
+  user_id: userIdSchema,
+  name: z.string().nullable(),
+  created_at: z.iso.datetime(),
+  last_used_at: z.iso.datetime().nullable(),
+  device_type: passkeyDeviceTypeSchema.nullable(),
+  backed_up: z.boolean(),
+  transports: z.array(authenticatorTransportSchema).optional(),
+});
+export type UserPasskey = z.infer<typeof userPasskeySchema>;
+
+export const userPasskeyListQuerySchema = userSubresourceListQuerySchema;
+export type UserPasskeyListQuery = z.infer<typeof userPasskeyListQuerySchema>;
+
+export const userPasskeyListResponseSchema = cursorPageSchema(userPasskeySchema);
+export type UserPasskeyListResponse = z.infer<typeof userPasskeyListResponseSchema>;
+
+export const userPasskeyDeleteResponseSchema = z.strictObject({
+  passkey_id: passkeyIdSchema,
+  deleted: z.literal(true),
+});
+export type UserPasskeyDeleteResponse = z.infer<typeof userPasskeyDeleteResponseSchema>;
+
+// ---------------------------------------------------------------------------
+// GET /users/:userId/sessions, DELETE /users/:userId/sessions/:sessionId,
+// DELETE /users/:userId/sessions
+// ---------------------------------------------------------------------------
+
+export const userSessionSchema = z.strictObject({
+  session_id: sessionIdSchema,
+  user_id: userIdSchema,
+  client_id: clientIdSchema,
+  device_name: z.string().nullable(),
+  created_at: z.iso.datetime(),
+  last_active_at: z.iso.datetime(),
+  idle_expires_at: z.iso.datetime(),
+  absolute_expires_at: z.iso.datetime(),
+  revoked_at: z.iso.datetime().nullable(),
+});
+export type UserSession = z.infer<typeof userSessionSchema>;
+
+export const userSessionListQuerySchema = userSubresourceListQuerySchema;
+export type UserSessionListQuery = z.infer<typeof userSessionListQuerySchema>;
+
+export const userSessionListResponseSchema = cursorPageSchema(userSessionSchema);
+export type UserSessionListResponse = z.infer<typeof userSessionListResponseSchema>;
+
+export const userSessionRevokeResponseSchema = z.strictObject({
+  session_id: sessionIdSchema,
+  revoked: z.literal(true),
+});
+export type UserSessionRevokeResponse = z.infer<typeof userSessionRevokeResponseSchema>;
+
+/** design.md §24.3: revoking all of a user's sessions bumps `UserSecurityDO.securityVersion`. */
+export const userSessionsRevokeAllResponseSchema = z.strictObject({
+  revoked: z.literal(true),
+});
+export type UserSessionsRevokeAllResponse = z.infer<typeof userSessionsRevokeAllResponseSchema>;