@smartcrab/contracts-management 0.1.0

package/dist/rbac.d.ts

@@ -0,0 +1,222 @@
+import { z } from "zod";
+/**
+ * Dashboard / Management API RBAC (design.md §27.2's role table, §11.2
+ * `workspace_members.role`).
+ */
+export declare const WORKSPACE_ROLES: readonly ["owner", "admin", "developer", "support", "billing", "viewer"];
+export declare const workspaceRoleSchema: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+    developer: "developer";
+    support: "support";
+    billing: "billing";
+    viewer: "viewer";
+}>;
+export type WorkspaceRole = (typeof WORKSPACE_ROLES)[number];
+/**
+ * The full set of grantable Management API scopes. Most use the
+ * `<resource>:<action>` form; protocol capabilities such as `introspect` are
+ * standalone. This is the declarative permission vocabulary both Management
+ * API keys (design.md §11.12) and dashboard roles (design.md §27.2) use.
+ */
+export declare const MANAGEMENT_SCOPES: readonly ["workspaces:read", "workspaces:write", "workspace_members:read", "projects:read", "projects:write", "environments:read", "environments:write", "clients:read", "clients:write", "clients:rotate_secret", "connections:read", "connections:write", "domains:read", "domains:write", "users:read", "users:write", "users:block", "users:delete", "user_identities:read", "user_identities:write", "user_passkeys:read", "user_passkeys:write", "user_sessions:read", "user_sessions:write", "user_data_jobs:read", "user_data_jobs:write", "webhooks:read", "webhooks:write", "webhooks:rotate_secret", "webhooks:test", "audit_events:read", "usage:read", "introspect", "billing:read", "billing:write", "api_keys:read", "api_keys:write", "impersonation:create"];
+export declare const managementScopeSchema: z.ZodEnum<{
+    "workspaces:read": "workspaces:read";
+    "workspaces:write": "workspaces:write";
+    "workspace_members:read": "workspace_members:read";
+    "projects:read": "projects:read";
+    "projects:write": "projects:write";
+    "environments:read": "environments:read";
+    "environments:write": "environments:write";
+    "clients:read": "clients:read";
+    "clients:write": "clients:write";
+    "clients:rotate_secret": "clients:rotate_secret";
+    "connections:read": "connections:read";
+    "connections:write": "connections:write";
+    "domains:read": "domains:read";
+    "domains:write": "domains:write";
+    "users:read": "users:read";
+    "users:write": "users:write";
+    "users:block": "users:block";
+    "users:delete": "users:delete";
+    "user_identities:read": "user_identities:read";
+    "user_identities:write": "user_identities:write";
+    "user_passkeys:read": "user_passkeys:read";
+    "user_passkeys:write": "user_passkeys:write";
+    "user_sessions:read": "user_sessions:read";
+    "user_sessions:write": "user_sessions:write";
+    "user_data_jobs:read": "user_data_jobs:read";
+    "user_data_jobs:write": "user_data_jobs:write";
+    "webhooks:read": "webhooks:read";
+    "webhooks:write": "webhooks:write";
+    "webhooks:rotate_secret": "webhooks:rotate_secret";
+    "webhooks:test": "webhooks:test";
+    "audit_events:read": "audit_events:read";
+    "usage:read": "usage:read";
+    introspect: "introspect";
+    "billing:read": "billing:read";
+    "billing:write": "billing:write";
+    "api_keys:read": "api_keys:read";
+    "api_keys:write": "api_keys:write";
+    "impersonation:create": "impersonation:create";
+}>;
+export type ManagementScope = (typeof MANAGEMENT_SCOPES)[number];
+/**
+ * Scopes that let an actor change how a user authenticates: linking/unlinking
+ * a social identity or adding/removing a passkey (design.md §12.3/§12.5,
+ * §25's "credential"). Deliberately narrower than "anything about the user
+ * account" — e.g. blocking a user or editing their display name is an
+ * account-state/profile change, not a credential change.
+ *
+ * design.md §25: "support roleだけではcredentialを変更できない." §27.4 forbids
+ * the same category of action during impersonation ("credential変更...は禁止").
+ */
+export declare const CREDENTIAL_MUTATING_SCOPES: readonly ["user_identities:write", "user_passkeys:write"];
+/** design.md §27.4: impersonation additionally forbids billing and API key operations. */
+export declare const IMPERSONATION_FORBIDDEN_SCOPES: readonly ["user_identities:write", "user_passkeys:write", "billing:read", "billing:write", "api_keys:read", "api_keys:write"];
+/**
+ * design.md §27.2 role → permission table:
+ *
+ * | Role      | 権限 |
+ * |-----------|------|
+ * | Owner     | 全操作、課金、Workspace削除 |
+ * | Admin     | Project、Environment、ユーザー管理 |
+ * | Developer | Client、Connection、Domain、Webhook |
+ * | Support   | ユーザー閲覧、session失効 |
+ * | Billing   | 課金・使用量 |
+ * | Viewer    | 読み取りのみ |
+ *
+ * `workspace_members:read` grant decision (no dedicated row in the table
+ * above — the assignment that added `GET /workspaces/:workspaceId/members`
+ * requires a defensible reading of it): granted to owner/admin/support/
+ * billing/viewer, withheld from developer. The Developer table lists "Client,
+ * Connection, Domain, Webhook" resources, with `introspect` as a standalone
+ * OAuth capability for resource-server token validation. The test below
+ * ensures the developer role gets no other resource prefixes. Every other
+ * role either reads broadly (`viewer`, "読み取りのみ") or needs the roster for
+ * its work (`admin` administers the workspace; `support`/`billing` deal with
+ * the workspace's people and billing contacts day to day).
+ */
+export declare const ROLE_SCOPES: Readonly<Record<WorkspaceRole, readonly ManagementScope[]>>;
+export declare const scopesForRole: (role: WorkspaceRole) => readonly ManagementScope[];
+export declare const roleHasScope: (role: WorkspaceRole, scope: ManagementScope) => boolean;
+/** A scope is read-only when it grants inspection without changing a resource or token state. */
+export declare const isReadOnlyScope: (scope: ManagementScope) => boolean;
+/** design.md §27.4: "OwnerまたはAdmin" may start an impersonation session. */
+export declare const IMPERSONATION_ALLOWED_ROLES: readonly ["owner", "admin"];
+export declare const impersonationAllowedRoleSchema: z.ZodEnum<{
+    owner: "owner";
+    admin: "admin";
+}>;
+export type ImpersonationAllowedRole = (typeof IMPERSONATION_ALLOWED_ROLES)[number];
+/** design.md §27.4: "最大15分". */
+export declare const IMPERSONATION_MAX_DURATION_MINUTES = 15;
+/** design.md §27.4: "理由入力" is a required, non-empty justification. */
+export declare const impersonationReasonSchema: z.ZodString;
+export declare const impersonationCreateRequestSchema: z.ZodObject<{
+    user_id: z.ZodString;
+    reason: z.ZodString;
+    duration_minutes: z.ZodNumber;
+}, z.core.$strict>;
+export type ImpersonationCreateRequest = z.infer<typeof impersonationCreateRequestSchema>;
+/**
+ * design.md §27.4: "UIに常時banner", "全操作をactorとimpersonated userの両方で
+ * 監査". The response carries both identities so the dashboard can render the
+ * mandatory banner and so every subsequent action can be dual-audited.
+ */
+export declare const impersonationSessionSchema: z.ZodObject<{
+    actor_user_id: z.ZodString;
+    impersonated_user_id: z.ZodString;
+    reason: z.ZodString;
+    started_at: z.ZodISODateTime;
+    expires_at: z.ZodISODateTime;
+    forbidden_scopes: z.ZodArray<z.ZodEnum<{
+        "workspaces:read": "workspaces:read";
+        "workspaces:write": "workspaces:write";
+        "workspace_members:read": "workspace_members:read";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "environments:read": "environments:read";
+        "environments:write": "environments:write";
+        "clients:read": "clients:read";
+        "clients:write": "clients:write";
+        "clients:rotate_secret": "clients:rotate_secret";
+        "connections:read": "connections:read";
+        "connections:write": "connections:write";
+        "domains:read": "domains:read";
+        "domains:write": "domains:write";
+        "users:read": "users:read";
+        "users:write": "users:write";
+        "users:block": "users:block";
+        "users:delete": "users:delete";
+        "user_identities:read": "user_identities:read";
+        "user_identities:write": "user_identities:write";
+        "user_passkeys:read": "user_passkeys:read";
+        "user_passkeys:write": "user_passkeys:write";
+        "user_sessions:read": "user_sessions:read";
+        "user_sessions:write": "user_sessions:write";
+        "user_data_jobs:read": "user_data_jobs:read";
+        "user_data_jobs:write": "user_data_jobs:write";
+        "webhooks:read": "webhooks:read";
+        "webhooks:write": "webhooks:write";
+        "webhooks:rotate_secret": "webhooks:rotate_secret";
+        "webhooks:test": "webhooks:test";
+        "audit_events:read": "audit_events:read";
+        "usage:read": "usage:read";
+        introspect: "introspect";
+        "billing:read": "billing:read";
+        "billing:write": "billing:write";
+        "api_keys:read": "api_keys:read";
+        "api_keys:write": "api_keys:write";
+        "impersonation:create": "impersonation:create";
+    }>>;
+}, z.core.$strict>;
+export type ImpersonationSession = z.infer<typeof impersonationSessionSchema>;
+export declare const impersonationCreateResponseSchema: z.ZodObject<{
+    actor_user_id: z.ZodString;
+    impersonated_user_id: z.ZodString;
+    reason: z.ZodString;
+    started_at: z.ZodISODateTime;
+    expires_at: z.ZodISODateTime;
+    forbidden_scopes: z.ZodArray<z.ZodEnum<{
+        "workspaces:read": "workspaces:read";
+        "workspaces:write": "workspaces:write";
+        "workspace_members:read": "workspace_members:read";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "environments:read": "environments:read";
+        "environments:write": "environments:write";
+        "clients:read": "clients:read";
+        "clients:write": "clients:write";
+        "clients:rotate_secret": "clients:rotate_secret";
+        "connections:read": "connections:read";
+        "connections:write": "connections:write";
+        "domains:read": "domains:read";
+        "domains:write": "domains:write";
+        "users:read": "users:read";
+        "users:write": "users:write";
+        "users:block": "users:block";
+        "users:delete": "users:delete";
+        "user_identities:read": "user_identities:read";
+        "user_identities:write": "user_identities:write";
+        "user_passkeys:read": "user_passkeys:read";
+        "user_passkeys:write": "user_passkeys:write";
+        "user_sessions:read": "user_sessions:read";
+        "user_sessions:write": "user_sessions:write";
+        "user_data_jobs:read": "user_data_jobs:read";
+        "user_data_jobs:write": "user_data_jobs:write";
+        "webhooks:read": "webhooks:read";
+        "webhooks:write": "webhooks:write";
+        "webhooks:rotate_secret": "webhooks:rotate_secret";
+        "webhooks:test": "webhooks:test";
+        "audit_events:read": "audit_events:read";
+        "usage:read": "usage:read";
+        introspect: "introspect";
+        "billing:read": "billing:read";
+        "billing:write": "billing:write";
+        "api_keys:read": "api_keys:read";
+        "api_keys:write": "api_keys:write";
+        "impersonation:create": "impersonation:create";
+    }>>;
+}, z.core.$strict>;
+export type ImpersonationCreateResponse = z.infer<typeof impersonationCreateResponseSchema>;

package/dist/rbac.js

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { userIdSchema } from "./primitives.js";
+/**
+ * Dashboard / Management API RBAC (design.md §27.2's role table, §11.2
+ * `workspace_members.role`).
+ */
+export const WORKSPACE_ROLES = [
+    "owner",
+    "admin",
+    "developer",
+    "support",
+    "billing",
+    "viewer",
+];
+export const workspaceRoleSchema = z.enum(WORKSPACE_ROLES);
+// ---------------------------------------------------------------------------
+// Scopes (design.md §26.1: "scope最小化" — Management API keys are granted a
+// minimal explicit scope list, not a raw role)
+// ---------------------------------------------------------------------------
+/**
+ * The full set of grantable Management API scopes. Most use the
+ * `<resource>:<action>` form; protocol capabilities such as `introspect` are
+ * standalone. This is the declarative permission vocabulary both Management
+ * API keys (design.md §11.12) and dashboard roles (design.md §27.2) use.
+ */
+export const MANAGEMENT_SCOPES = [
+    "workspaces:read",
+    "workspaces:write",
+    // `GET /workspaces/:workspaceId/members` (design.md §11.2, §27.3's
+    // Security settings screen, §27.2's RBAC table). See the `ROLE_SCOPES`
+    // doc comment below for which roles are granted this.
+    "workspace_members:read",
+    "projects:read",
+    "projects:write",
+    "environments:read",
+    "environments:write",
+    "clients:read",
+    "clients:write",
+    "clients:rotate_secret",
+    "connections:read",
+    "connections:write",
+    "domains:read",
+    "domains:write",
+    "users:read",
+    "users:write",
+    "users:block",
+    "users:delete",
+    "user_identities:read",
+    "user_identities:write",
+    "user_passkeys:read",
+    "user_passkeys:write",
+    "user_sessions:read",
+    "user_sessions:write",
+    "user_data_jobs:read",
+    "user_data_jobs:write",
+    "webhooks:read",
+    "webhooks:write",
+    "webhooks:rotate_secret",
+    "webhooks:test",
+    "audit_events:read",
+    "usage:read",
+    // Scoped Management API key permission for POST /oauth2/introspect
+    // (design.md §15.8); not a resource CRUD scope.
+    "introspect",
+    "billing:read",
+    "billing:write",
+    "api_keys:read",
+    "api_keys:write",
+    "impersonation:create",
+];
+export const managementScopeSchema = z.enum(MANAGEMENT_SCOPES);
+/**
+ * Scopes that let an actor change how a user authenticates: linking/unlinking
+ * a social identity or adding/removing a passkey (design.md §12.3/§12.5,
+ * §25's "credential"). Deliberately narrower than "anything about the user
+ * account" — e.g. blocking a user or editing their display name is an
+ * account-state/profile change, not a credential change.
+ *
+ * design.md §25: "support roleだけではcredentialを変更できない." §27.4 forbids
+ * the same category of action during impersonation ("credential変更...は禁止").
+ */
+export const CREDENTIAL_MUTATING_SCOPES = [
+    "user_identities:write",
+    "user_passkeys:write",
+];
+/** design.md §27.4: impersonation additionally forbids billing and API key operations. */
+export const IMPERSONATION_FORBIDDEN_SCOPES = [
+    ...CREDENTIAL_MUTATING_SCOPES,
+    "billing:read",
+    "billing:write",
+    "api_keys:read",
+    "api_keys:write",
+];
+/**
+ * design.md §27.2 role → permission table:
+ *
+ * | Role      | 権限 |
+ * |-----------|------|
+ * | Owner     | 全操作、課金、Workspace削除 |
+ * | Admin     | Project、Environment、ユーザー管理 |
+ * | Developer | Client、Connection、Domain、Webhook |
+ * | Support   | ユーザー閲覧、session失効 |
+ * | Billing   | 課金・使用量 |
+ * | Viewer    | 読み取りのみ |
+ *
+ * `workspace_members:read` grant decision (no dedicated row in the table
+ * above — the assignment that added `GET /workspaces/:workspaceId/members`
+ * requires a defensible reading of it): granted to owner/admin/support/
+ * billing/viewer, withheld from developer. The Developer table lists "Client,
+ * Connection, Domain, Webhook" resources, with `introspect` as a standalone
+ * OAuth capability for resource-server token validation. The test below
+ * ensures the developer role gets no other resource prefixes. Every other
+ * role either reads broadly (`viewer`, "読み取りのみ") or needs the roster for
+ * its work (`admin` administers the workspace; `support`/`billing` deal with
+ * the workspace's people and billing contacts day to day).
+ */
+export const ROLE_SCOPES = {
+    owner: MANAGEMENT_SCOPES,
+    admin: [
+        "workspaces:read",
+        "workspace_members:read",
+        "projects:read",
+        "projects:write",
+        "environments:read",
+        "environments:write",
+        "introspect",
+        "users:read",
+        "users:write",
+        "users:block",
+        "users:delete",
+        "user_identities:read",
+        "user_identities:write",
+        "user_passkeys:read",
+        "user_passkeys:write",
+        "user_sessions:read",
+        "user_sessions:write",
+        "user_data_jobs:read",
+        "user_data_jobs:write",
+        "audit_events:read",
+        "impersonation:create",
+    ],
+    developer: [
+        "clients:read",
+        "introspect",
+        "clients:write",
+        "clients:rotate_secret",
+        "connections:read",
+        "connections:write",
+        "domains:read",
+        "domains:write",
+        "webhooks:read",
+        "webhooks:write",
+        "webhooks:rotate_secret",
+        "webhooks:test",
+    ],
+    support: [
+        "users:read",
+        "user_identities:read",
+        "user_passkeys:read",
+        "user_sessions:read",
+        "user_sessions:write",
+        "workspace_members:read",
+    ],
+    billing: [
+        "billing:read",
+        "billing:write",
+        "usage:read",
+        "workspaces:read",
+        "workspace_members:read",
+    ],
+    viewer: [
+        "workspaces:read",
+        "workspace_members:read",
+        "projects:read",
+        "environments:read",
+        "clients:read",
+        "connections:read",
+        "domains:read",
+        "users:read",
+        "user_identities:read",
+        "user_passkeys:read",
+        "user_sessions:read",
+        "user_data_jobs:read",
+        "webhooks:read",
+        "audit_events:read",
+        "usage:read",
+        "billing:read",
+        "api_keys:read",
+    ],
+};
+export const scopesForRole = (role) => ROLE_SCOPES[role];
+export const roleHasScope = (role, scope) => ROLE_SCOPES[role].includes(scope);
+/** A scope is read-only when it grants inspection without changing a resource or token state. */
+export const isReadOnlyScope = (scope) => scope === "introspect" || scope.endsWith(":read");
+// ---------------------------------------------------------------------------
+// Impersonation (design.md §27.4)
+// ---------------------------------------------------------------------------
+/** design.md §27.4: "OwnerまたはAdmin" may start an impersonation session. */
+export const IMPERSONATION_ALLOWED_ROLES = [
+    "owner",
+    "admin",
+];
+export const impersonationAllowedRoleSchema = z.enum(IMPERSONATION_ALLOWED_ROLES);
+/** design.md §27.4: "最大15分". */
+export const IMPERSONATION_MAX_DURATION_MINUTES = 15;
+/** design.md §27.4: "理由入力" is a required, non-empty justification. */
+export const impersonationReasonSchema = z.string().min(10).max(1000);
+export const impersonationCreateRequestSchema = z.strictObject({
+    user_id: userIdSchema,
+    reason: impersonationReasonSchema,
+    duration_minutes: z.number().int().min(1).max(IMPERSONATION_MAX_DURATION_MINUTES),
+});
+/**
+ * design.md §27.4: "UIに常時banner", "全操作をactorとimpersonated userの両方で
+ * 監査". The response carries both identities so the dashboard can render the
+ * mandatory banner and so every subsequent action can be dual-audited.
+ */
+export const impersonationSessionSchema = z.strictObject({
+    actor_user_id: userIdSchema,
+    impersonated_user_id: userIdSchema,
+    reason: impersonationReasonSchema,
+    started_at: z.iso.datetime(),
+    expires_at: z.iso.datetime(),
+    forbidden_scopes: z.array(managementScopeSchema),
+});
+export const impersonationCreateResponseSchema = impersonationSessionSchema;

package/dist/usage.d.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+/**
+ * `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 declare const MAU_FREE_TIER_LIMIT = 30000;
+/** design.md §28.5: "80%、95%、100%到達時にOwner/Billing roleへ通知". */
+export declare const MAU_THRESHOLD_LEVELS: readonly [80, 95, 100];
+export declare const mauThresholdLevelSchema: z.ZodUnion<readonly [z.ZodLiteral<80>, z.ZodLiteral<95>, z.ZodLiteral<100>]>;
+export type MauThresholdLevel = (typeof MAU_THRESHOLD_LEVELS)[number];
+/** `billing_month` wire format: `YYYY-MM` (design.md §12.10 `mau_month.billing_month`). */
+export declare const billingMonthSchema: z.ZodString;
+/**
+ * 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 declare const GRACE_PERIOD_STATUSES: readonly ["none", "active", "expired"];
+export declare const gracePeriodStatusSchema: z.ZodEnum<{
+    expired: "expired";
+    none: "none";
+    active: "active";
+}>;
+export type GracePeriodStatus = (typeof GRACE_PERIOD_STATUSES)[number];
+export declare const gracePeriodSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        expired: "expired";
+        none: "none";
+        active: "active";
+    }>;
+    started_at: z.ZodNullable<z.ZodISODateTime>;
+    expires_at: z.ZodNullable<z.ZodISODateTime>;
+    new_user_creation_blocked: z.ZodBoolean;
+}, z.core.$strict>;
+export type GracePeriod = z.infer<typeof gracePeriodSchema>;
+declare const mauEnvironmentBreakdownSchema: z.ZodObject<{
+    environment_id: z.ZodString;
+    count: z.ZodNumber;
+}, z.core.$strict>;
+export type MauEnvironmentBreakdown = z.infer<typeof mauEnvironmentBreakdownSchema>;
+export declare const mauUsageResponseSchema: z.ZodObject<{
+    workspace_id: z.ZodString;
+    billing_month: z.ZodString;
+    total_count: z.ZodNumber;
+    free_tier_limit: z.ZodLiteral<30000>;
+    percent_used: z.ZodNumber;
+    threshold_reached: z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<80>, z.ZodLiteral<95>, z.ZodLiteral<100>]>>;
+    billing_activated: z.ZodBoolean;
+    grace_period: z.ZodObject<{
+        status: z.ZodEnum<{
+            expired: "expired";
+            none: "none";
+            active: "active";
+        }>;
+        started_at: z.ZodNullable<z.ZodISODateTime>;
+        expires_at: z.ZodNullable<z.ZodISODateTime>;
+        new_user_creation_blocked: z.ZodBoolean;
+    }, z.core.$strict>;
+    environments: z.ZodArray<z.ZodObject<{
+        environment_id: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type MauUsageResponse = z.infer<typeof mauUsageResponseSchema>;
+export declare const mauUsageQuerySchema: z.ZodObject<{
+    billing_month: z.ZodOptional<z.ZodString>;
+    environment_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type MauUsageQuery = z.infer<typeof mauUsageQuerySchema>;
+export {};

package/dist/usage.js

@@ -0,0 +1,52 @@
+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];
+export const mauThresholdLevelSchema = z.union([z.literal(80), z.literal(95), z.literal(100)]);
+/** `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"];
+export const gracePeriodStatusSchema = z.enum(GRACE_PERIOD_STATUSES);
+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(),
+});
+const mauEnvironmentBreakdownSchema = z.strictObject({
+    environment_id: environmentIdSchema,
+    count: z.number().int().nonnegative(),
+});
+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 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(),
+});