@smartcrab/contracts-management 0.1.0

package/dist/common.js

@@ -0,0 +1,99 @@
+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),
+});
+/**
+ * Generic cursor-paginated list envelope: `{ items, next_cursor }`.
+ * `next_cursor` is `null` once the caller has reached the last page.
+ */
+export const cursorPageSchema = (itemSchema) => z.strictObject({
+    items: z.array(itemSchema),
+    next_cursor: z.string().min(1).nullable(),
+});
+// ---------------------------------------------------------------------------
+// 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,
+});
+// ---------------------------------------------------------------------------
+// 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);
+/** Header carried by every conditional `PATCH`/`DELETE` request. */
+export const ifMatchHeaderSchema = z.strictObject({
+    "if-match": etagSchema,
+});
+// ---------------------------------------------------------------------------
+// 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 const requestIdHeaderSchema = z.strictObject({
+    "x-request-id": requestIdSchema,
+});
+// ---------------------------------------------------------------------------
+// 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(),
+});

package/dist/connections.d.ts

@@ -0,0 +1,201 @@
+import { z } from "zod";
+/**
+ * `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 declare const CONNECTION_MODES: readonly ["managed", "byo"];
+export declare const connectionModeSchema: z.ZodEnum<{
+    managed: "managed";
+    byo: "byo";
+}>;
+export type ConnectionMode = (typeof CONNECTION_MODES)[number];
+export declare const CONNECTION_STATUSES: readonly ["active", "disabled"];
+export declare const connectionStatusSchema: z.ZodEnum<{
+    active: "active";
+    disabled: "disabled";
+}>;
+export type ConnectionStatus = (typeof CONNECTION_STATUSES)[number];
+export declare const connectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    provider: z.ZodEnum<{
+        google: "google";
+        apple: "apple";
+        github: "github";
+        microsoft: "microsoft";
+        generic_oidc: "generic_oidc";
+    }>;
+    mode: z.ZodEnum<{
+        managed: "managed";
+        byo: "byo";
+    }>;
+    provider_key: z.ZodString;
+    issuer: z.ZodNullable<z.ZodURL>;
+    provider_client_id: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    profile_mapping: z.ZodRecord<z.ZodString, z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>;
+    owner_confirmed: z.ZodBoolean;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type Connection = z.infer<typeof connectionSchema>;
+export declare const connectionListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    environment_id: z.ZodString;
+    provider: z.ZodOptional<z.ZodEnum<{
+        google: "google";
+        apple: "apple";
+        github: "github";
+        microsoft: "microsoft";
+        generic_oidc: "generic_oidc";
+    }>>;
+}, z.core.$strip>;
+export type ConnectionListQuery = z.infer<typeof connectionListQuerySchema>;
+export declare const connectionListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        environment_id: z.ZodString;
+        provider: z.ZodEnum<{
+            google: "google";
+            apple: "apple";
+            github: "github";
+            microsoft: "microsoft";
+            generic_oidc: "generic_oidc";
+        }>;
+        mode: z.ZodEnum<{
+            managed: "managed";
+            byo: "byo";
+        }>;
+        provider_key: z.ZodString;
+        issuer: z.ZodNullable<z.ZodURL>;
+        provider_client_id: z.ZodString;
+        scopes: z.ZodArray<z.ZodString>;
+        profile_mapping: z.ZodRecord<z.ZodString, z.ZodString>;
+        status: z.ZodEnum<{
+            active: "active";
+            disabled: "disabled";
+        }>;
+        owner_confirmed: z.ZodBoolean;
+        created_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type ConnectionListResponse = z.infer<typeof connectionListResponseSchema>;
+/**
+ * `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 declare const connectionCreateRequestSchema: z.ZodObject<{
+    environment_id: z.ZodString;
+    provider: z.ZodEnum<{
+        google: "google";
+        apple: "apple";
+        github: "github";
+        microsoft: "microsoft";
+        generic_oidc: "generic_oidc";
+    }>;
+    mode: z.ZodEnum<{
+        managed: "managed";
+        byo: "byo";
+    }>;
+    provider_key: z.ZodString;
+    issuer: z.ZodOptional<z.ZodURL>;
+    provider_client_id: z.ZodString;
+    provider_client_secret: z.ZodString;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    profile_mapping: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strict>;
+export type ConnectionCreateRequest = z.infer<typeof connectionCreateRequestSchema>;
+export declare const connectionCreateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    provider: z.ZodEnum<{
+        google: "google";
+        apple: "apple";
+        github: "github";
+        microsoft: "microsoft";
+        generic_oidc: "generic_oidc";
+    }>;
+    mode: z.ZodEnum<{
+        managed: "managed";
+        byo: "byo";
+    }>;
+    provider_key: z.ZodString;
+    issuer: z.ZodNullable<z.ZodURL>;
+    provider_client_id: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    profile_mapping: z.ZodRecord<z.ZodString, z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>;
+    owner_confirmed: z.ZodBoolean;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ConnectionCreateResponse = z.infer<typeof connectionCreateResponseSchema>;
+export declare const connectionUpdateRequestSchema: z.ZodObject<{
+    issuer: z.ZodOptional<z.ZodURL>;
+    provider_client_id: z.ZodOptional<z.ZodString>;
+    provider_client_secret: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    profile_mapping: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>>;
+    owner_confirmed: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ConnectionUpdateRequest = z.infer<typeof connectionUpdateRequestSchema>;
+export declare const connectionUpdateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    provider: z.ZodEnum<{
+        google: "google";
+        apple: "apple";
+        github: "github";
+        microsoft: "microsoft";
+        generic_oidc: "generic_oidc";
+    }>;
+    mode: z.ZodEnum<{
+        managed: "managed";
+        byo: "byo";
+    }>;
+    provider_key: z.ZodString;
+    issuer: z.ZodNullable<z.ZodURL>;
+    provider_client_id: z.ZodString;
+    scopes: z.ZodArray<z.ZodString>;
+    profile_mapping: z.ZodRecord<z.ZodString, z.ZodString>;
+    status: z.ZodEnum<{
+        active: "active";
+        disabled: "disabled";
+    }>;
+    owner_confirmed: z.ZodBoolean;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+}, z.core.$strict>;
+export type ConnectionUpdateResponse = z.infer<typeof connectionUpdateResponseSchema>;
+export declare const connectionDeleteResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type ConnectionDeleteResponse = z.infer<typeof connectionDeleteResponseSchema>;

package/dist/connections.js

@@ -0,0 +1,107 @@
+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"];
+export const connectionModeSchema = z.enum(CONNECTION_MODES);
+export const CONNECTION_STATUSES = ["active", "disabled"];
+export const connectionStatusSchema = z.enum(CONNECTION_STATUSES);
+/** 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(),
+});
+// ---------------------------------------------------------------------------
+// GET /connections
+// ---------------------------------------------------------------------------
+export const connectionListQuerySchema = paginationQuerySchema.extend({
+    environment_id: environmentIdSchema,
+    provider: socialProviderSchema.optional(),
+});
+export const connectionListResponseSchema = cursorPageSchema(connectionSchema);
+// ---------------------------------------------------------------------------
+// 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 const connectionCreateResponseSchema = connectionSchema;
+// ---------------------------------------------------------------------------
+// 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 const connectionUpdateResponseSchema = connectionSchema;
+// ---------------------------------------------------------------------------
+// DELETE /connections/:connectionId
+// ---------------------------------------------------------------------------
+export const connectionDeleteResponseSchema = z.strictObject({
+    id: connectionIdSchema,
+    deleted: z.literal(true),
+});

package/dist/domains.d.ts

@@ -0,0 +1,167 @@
+import { z } from "zod";
+/**
+ * `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 declare const CUSTOM_DOMAIN_STATUSES: readonly ["pending", "active", "moved", "failed", "deleting"];
+export declare const customDomainStatusSchema: z.ZodEnum<{
+    failed: "failed";
+    active: "active";
+    pending: "pending";
+    moved: "moved";
+    deleting: "deleting";
+}>;
+export type CustomDomainStatus = (typeof CUSTOM_DOMAIN_STATUSES)[number];
+/** Canonicalize a custom hostname at an external boundary before persistence or routing. */
+export declare const canonicalizeCustomHostname: (hostname: string) => string;
+export declare const domainSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>;
+    rp_enabled: z.ZodBoolean;
+    validation_errors: z.ZodArray<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    activated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type Domain = z.infer<typeof domainSchema>;
+export declare const domainListQuerySchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    environment_id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>>;
+}, z.core.$strip>;
+export type DomainListQuery = z.infer<typeof domainListQuerySchema>;
+export declare const domainListResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        environment_id: z.ZodString;
+        hostname: z.ZodString;
+        status: z.ZodEnum<{
+            failed: "failed";
+            active: "active";
+            pending: "pending";
+            moved: "moved";
+            deleting: "deleting";
+        }>;
+        rp_enabled: z.ZodBoolean;
+        validation_errors: z.ZodArray<z.ZodString>;
+        created_at: z.ZodISODateTime;
+        updated_at: z.ZodISODateTime;
+        activated_at: z.ZodNullable<z.ZodISODateTime>;
+    }, z.core.$strict>>;
+    next_cursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DomainListResponse = z.infer<typeof domainListResponseSchema>;
+export declare const domainCreateRequestSchema: z.ZodObject<{
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    rp_enabled: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export type DomainCreateRequest = z.infer<typeof domainCreateRequestSchema>;
+/** A freshly created domain always starts `pending` validation (design.md §11.9). */
+export declare const domainCreateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>;
+    rp_enabled: z.ZodBoolean;
+    validation_errors: z.ZodArray<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    activated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type DomainCreateResponse = z.infer<typeof domainCreateResponseSchema>;
+export declare const domainGetResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>;
+    rp_enabled: z.ZodBoolean;
+    validation_errors: z.ZodArray<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    activated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type DomainGetResponse = z.infer<typeof domainGetResponseSchema>;
+export declare const domainDeleteResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    deleted: z.ZodLiteral<true>;
+}, z.core.$strict>;
+export type DomainDeleteResponse = z.infer<typeof domainDeleteResponseSchema>;
+/**
+ * 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 declare const domainUpdateRequestSchema: z.ZodObject<{
+    rp_enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export type DomainUpdateRequest = z.infer<typeof domainUpdateRequestSchema>;
+export declare const domainUpdateResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>;
+    rp_enabled: z.ZodBoolean;
+    validation_errors: z.ZodArray<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    activated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type DomainUpdateResponse = z.infer<typeof domainUpdateResponseSchema>;
+export declare const domainRetryValidationRequestSchema: z.ZodObject<{}, z.core.$strict>;
+export type DomainRetryValidationRequest = z.infer<typeof domainRetryValidationRequestSchema>;
+/** Retrying resets `status` to `pending` and clears prior `validation_errors`. */
+export declare const domainRetryValidationResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    environment_id: z.ZodString;
+    hostname: z.ZodString;
+    status: z.ZodEnum<{
+        failed: "failed";
+        active: "active";
+        pending: "pending";
+        moved: "moved";
+        deleting: "deleting";
+    }>;
+    rp_enabled: z.ZodBoolean;
+    validation_errors: z.ZodArray<z.ZodString>;
+    created_at: z.ZodISODateTime;
+    updated_at: z.ZodISODateTime;
+    activated_at: z.ZodNullable<z.ZodISODateTime>;
+}, z.core.$strict>;
+export type DomainRetryValidationResponse = z.infer<typeof domainRetryValidationResponseSchema>;

package/dist/domains.js

@@ -0,0 +1,74 @@
+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"];
+export const customDomainStatusSchema = z.enum(CUSTOM_DOMAIN_STATUSES);
+const customHostnameSchema = z.string().min(1).max(253);
+/** Canonicalize a custom hostname at an external boundary before persistence or routing. */
+export const canonicalizeCustomHostname = (hostname) => 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(),
+});
+// ---------------------------------------------------------------------------
+// GET /domains
+// ---------------------------------------------------------------------------
+export const domainListQuerySchema = paginationQuerySchema.extend({
+    environment_id: environmentIdSchema,
+    status: customDomainStatusSchema.optional(),
+});
+export const domainListResponseSchema = cursorPageSchema(domainSchema);
+// ---------------------------------------------------------------------------
+// POST /domains
+// ---------------------------------------------------------------------------
+export const domainCreateRequestSchema = z.strictObject({
+    environment_id: environmentIdSchema,
+    hostname: customHostnameSchema,
+    rp_enabled: z.boolean().default(false),
+});
+/** A freshly created domain always starts `pending` validation (design.md §11.9). */
+export const domainCreateResponseSchema = domainSchema;
+// ---------------------------------------------------------------------------
+// GET /domains/:domainId
+// ---------------------------------------------------------------------------
+export const domainGetResponseSchema = domainSchema;
+// ---------------------------------------------------------------------------
+// DELETE /domains/:domainId
+// ---------------------------------------------------------------------------
+export const domainDeleteResponseSchema = z.strictObject({
+    id: domainIdSchema,
+    deleted: z.literal(true),
+});
+// ---------------------------------------------------------------------------
+// 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 const domainUpdateResponseSchema = domainSchema;
+// ---------------------------------------------------------------------------
+// POST /domains/:domainId/retry-validation
+// ---------------------------------------------------------------------------
+export const domainRetryValidationRequestSchema = z.strictObject({});
+/** Retrying resets `status` to `pending` and clears prior `validation_errors`. */
+export const domainRetryValidationResponseSchema = domainSchema;