slotlock 0.2.0 → 0.5.0

package/self-host.js

@@ -3,20 +3,24 @@
 // supplies it the same way and nothing is read from a file or a request. A missing or weak secret
 // stops a command before it connects anywhere, and no secret is written to a log line or an error.
 // The one exception is the API key `key create` prints: that output is the key's only copy.
+import { createSlotlockWebhookSender, deliverSlotlockWebhooks, startSlotlockWebhookDelivery, } from './webhooks.js';
 import { createHash, timingSafeEqual } from 'node:crypto';
 import { parseArgs } from 'node:util';
 import postgres from 'postgres';
 import { createSlotlockAgentServer, slotlockAgentOperationScope, } from './agent-server.js';
 import { createSlotlockStoreAgentBackend, createSlotlockStoreApplicationBackend, } from './agent-store-backend.js';
 import { SLOTLOCK_API_KEY_DEFAULT_SCOPES, SLOTLOCK_API_KEY_MAX_LIFETIME_DAYS, SLOTLOCK_API_KEY_SCOPES, createSlotlockApiKeyAuthenticator, createSlotlockApiKeyStore, slotlockBearerCredential, } from './api-keys.js';
-import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockDashboardState, } from './dashboard.js';
-import { SECRET_HINT, SlotlockConfigError, optional, readAvailability, readDashboardConfig, readSecret, readServerUrl, } from './config.js';
+import { createSlotlockDashboard, createSlotlockDashboardResources, createSlotlockAcceptanceRecords, createSlotlockDashboardState, } from './dashboard.js';
+import { SECRET_HINT, SlotlockConfigError, formatSlotlockRate, optional, readAvailability, readDashboardConfig, readDashboardOrganizations, readLimits, readSecret, readServerUrl, readTrustedProxyHeader, slotlockKeySubscriptions, } from './config.js';
+import { parseBookingRules } from './booking-rules.js';
 import { SLOTLOCK_APPLICATION_SCOPE } from './application-api.js';
 import { SLOTLOCK_DASHBOARD_FUNCTIONS, SLOTLOCK_TENANT_TABLES } from './ddl.js';
 import { maintainSlotlockTenant, startSlotlockMaintenance, withSlotlockMaintenanceLock, } from './maintenance.js';
 import { createSlotlockNodeServer, } from './node-server.js';
+import { createSlotlockMetrics } from './metrics.js';
 import { slotlockPackageVersion } from './package-version.js';
-import { createSlotlockStore } from './store.js';
+import { createSlotlockRequestLimits } from './rate-limit.js';
+import { assertSlotlockSchemaCurrent, createSlotlockStore, } from './store.js';
 import { parseAvailabilityRules } from './weekly-hours.js';
 export { SlotlockConfigError };
 /** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
@@ -26,21 +30,29 @@ export const SLOTLOCK_ENVIRONMENT_VARIABLES = Object.freeze([
     'SLOTLOCK_AUTH_TOKEN',
     'SLOTLOCK_CONFIRMATION_SECRET',
     'SLOTLOCK_CONFIRM_WRITES',
+    'SLOTLOCK_METRICS_TOKEN',
     'SLOTLOCK_PUBLIC_URL',
     'SLOTLOCK_TENANT',
     'SLOTLOCK_AVAILABILITY',
     'SLOTLOCK_REST_API',
+    'SLOTLOCK_RETENTION_DAYS',
+    'SLOTLOCK_WEBHOOKS',
+    'SLOTLOCK_SHARED_LIMITS',
+    'SLOTLOCK_LIMITS',
+    'SLOTLOCK_TRUSTED_PROXY_HEADER',
     'SLOTLOCK_GITHUB_CLIENT_ID',
     'SLOTLOCK_GITHUB_CLIENT_SECRET',
     'SLOTLOCK_SESSION_SECRET',
     'SLOTLOCK_DASHBOARD_USERS',
+    'SLOTLOCK_DASHBOARD_ORGS',
+    'SLOTLOCK_DASHBOARD_NAME',
     'HOST',
     'PORT',
 ]);
 const DEFAULT_HOST = '127.0.0.1';
 const DEFAULT_PORT = 8080;
 const DEFAULT_TENANT = 'default';
-/** The principal the server token resolves to: it acts in SLOTLOCK_TENANT with every scope. */
+/** The principal the server token resolves to: it acts in SLOTLOCK_TENANT with read and write. */
 const SELF_HOST_SUBJECT = 'self-host';
 /** Who `key create` records as a key's creator. */
 const CLI_KEY_CREATOR = 'cli';
@@ -56,6 +68,8 @@ const SERVE_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1_000;
 const MAINTAIN_MAX_PASSES = 100;
 const WRITE_OPERATIONS = [
     'slotlock_create_event',
+    'slotlock_book_together',
+    'slotlock_book_pool',
     'slotlock_update_event',
     'slotlock_delete_event',
 ];
@@ -67,6 +81,12 @@ const SERVED_OPERATIONS = new Set([
     'slotlock_list_resources',
     'slotlock_get_free_busy',
     'slotlock_find_next_available',
+    'slotlock_find_available_slots',
+    'slotlock_hold_slots',
+    'slotlock_release_slots',
+    'slotlock_book_together',
+    'slotlock_book_pool',
+    'slotlock_get_pool_availability',
     'slotlock_create_event',
     'slotlock_get_event',
     'slotlock_list_events',
@@ -74,8 +94,13 @@ const SERVED_OPERATIONS = new Set([
     'slotlock_delete_event',
 ]);
 const HEALTH_QUERY_TIMEOUT_MS = 2_000;
+/** How long one database check answers /healthz, so a flood of health checks is not one of queries. */
+const HEALTH_RESULT_MS = 1_000;
 const HEALTHCHECK_TIMEOUT_MS = 5_000;
+/** One pool for every tenant; SLOTLOCK_LIMITS `tenant_transactions` (config.ts) goes up to it. */
 const POOL_SIZE = 10;
+/** How long a request's transaction waits for any one lock before it answers 503 `server_busy`. */
+const SERVE_LOCK_TIMEOUT_MS = 5_000;
 const RESOURCE_PAGE_SIZE = 1_000;
 function readDatabaseUrl(env, name) {
     const value = optional(env, name);
@@ -121,7 +146,7 @@ function readTenant(env) {
     return value;
 }
 function readConfirmWrites(env) {
-    const value = optional(env, 'SLOTLOCK_CONFIRM_WRITES') ?? 'all';
+    const value = optional(env, 'SLOTLOCK_CONFIRM_WRITES') ?? 'none';
     if (value === 'all')
         return [...WRITE_OPERATIONS];
     if (value === 'none')
@@ -143,11 +168,38 @@ export function readSlotlockDatabaseConfig(env) {
         throw new SlotlockConfigError('DATABASE_URL is required: the postgres:// URL of the role Slotlock serves as');
     }
     const config = { databaseUrl, tenantRef: readTenant(env) };
+    const retentionDays = readRetentionDays(env);
+    if (retentionDays !== undefined)
+        config.retentionDays = retentionDays;
     const migrateDatabaseUrl = readDatabaseUrl(env, 'SLOTLOCK_MIGRATE_DATABASE_URL');
     if (migrateDatabaseUrl !== undefined)
         config.migrateDatabaseUrl = migrateDatabaseUrl;
     return config;
 }
+function readWebhooks(env) {
+    const value = optional(env, 'SLOTLOCK_WEBHOOKS') ?? 'on';
+    if (value !== 'on' && value !== 'off' && value !== 'private') {
+        throw new SlotlockConfigError('SLOTLOCK_WEBHOOKS must be on, off or private');
+    }
+    return value;
+}
+/** SLOTLOCK_RETENTION_DAYS: how long history is kept, in days (createSlotlockStore's `retentionDays`). */
+function readRetentionDays(env) {
+    const value = optional(env, 'SLOTLOCK_RETENTION_DAYS');
+    if (value === undefined)
+        return undefined;
+    if (!/^[1-9]\d{0,3}$/.test(value) || Number(value) > 3_650) {
+        throw new SlotlockConfigError('SLOTLOCK_RETENTION_DAYS must be a whole number of days from 1 to 3650');
+    }
+    return Number(value);
+}
+function readSharedLimits(env) {
+    const value = optional(env, 'SLOTLOCK_SHARED_LIMITS') ?? 'off';
+    if (value !== 'on' && value !== 'off') {
+        throw new SlotlockConfigError('SLOTLOCK_SHARED_LIMITS must be on or off');
+    }
+    return value === 'on';
+}
 function readRestApi(env) {
     const value = optional(env, 'SLOTLOCK_REST_API') ?? 'on';
     if (value !== 'on' && value !== 'off') {
@@ -161,7 +213,7 @@ export function readSlotlockServeConfig(env) {
     const confirmWrites = readConfirmWrites(env);
     const confirmationSecret = readSecret(env, 'SLOTLOCK_CONFIRMATION_SECRET');
     if (confirmWrites.length > 0 && confirmationSecret === undefined) {
-        throw new SlotlockConfigError(`SLOTLOCK_CONFIRMATION_SECRET is required while SLOTLOCK_CONFIRM_WRITES guards writes (the default): it signs each pending confirmation; ${SECRET_HINT}, or set SLOTLOCK_CONFIRM_WRITES=none to let agents write without asking a person`);
+        throw new SlotlockConfigError(`SLOTLOCK_CONFIRMATION_SECRET is required while SLOTLOCK_CONFIRM_WRITES guards writes: it signs each pending confirmation; ${SECRET_HINT}, or set SLOTLOCK_CONFIRM_WRITES=none (the default) to let agents write without asking a person`);
     }
     if (confirmationSecret !== undefined &&
         authToken !== undefined &&
@@ -177,12 +229,34 @@ export function readSlotlockServeConfig(env) {
         confirmWrites,
         availability: readAvailability(env),
         restApi: readRestApi(env),
+        webhooks: readWebhooks(env),
+        sharedLimits: readSharedLimits(env),
+        limits: readLimits(env),
     };
+    const trustedProxyHeader = readTrustedProxyHeader(env);
+    if (trustedProxyHeader !== undefined)
+        config.trustedProxyHeader = trustedProxyHeader;
     if (authToken !== undefined)
         config.authToken = authToken;
+    const metricsToken = readSecret(env, 'SLOTLOCK_METRICS_TOKEN');
+    if (metricsToken !== undefined) {
+        const others = [
+            authToken,
+            confirmationSecret,
+            env.SLOTLOCK_SESSION_SECRET?.trim(),
+            env.SLOTLOCK_GITHUB_CLIENT_SECRET?.trim(),
+        ];
+        if (others.includes(metricsToken)) {
+            throw new SlotlockConfigError('SLOTLOCK_METRICS_TOKEN must differ from every other secret');
+        }
+        config.metricsToken = metricsToken;
+    }
     const dashboard = readDashboardConfig(env);
     if (dashboard !== undefined)
         config.dashboard = dashboard;
+    const organizations = readDashboardOrganizations(env);
+    if (organizations !== undefined)
+        config.organizations = organizations;
     if (confirmWrites.length > 0 && confirmationSecret !== undefined) {
         config.confirmationSecret = confirmationSecret;
     }
@@ -219,8 +293,8 @@ export function createSlotlockTokenAuthenticator(token, principal) {
 }
 /**
  * What `serve` lets a principal call: a served operation its scopes cover. The server token's
- * principal carries every scope; a principal without scopes is refused everything here, though the
- * agent server alone would leave it to this function.
+ * principal carries read and write, never admin; a principal without scopes is refused everything
+ * here, though the agent server alone would leave it to this function.
  */
 export function authorizeSlotlockServeOperation(args) {
     return (SERVED_OPERATIONS.has(args.operation) &&
@@ -234,6 +308,7 @@ function secretsIn(env) {
         'SLOTLOCK_CONFIRMATION_SECRET',
         'SLOTLOCK_GITHUB_CLIENT_SECRET',
         'SLOTLOCK_SESSION_SECRET',
+        'SLOTLOCK_METRICS_TOKEN',
     ]) {
         const value = env[name]?.trim();
         if (value)
@@ -256,7 +331,10 @@ function secretsIn(env) {
     // Longest first, so a URL is replaced whole rather than around its password.
     return [...new Set(secrets)].sort((a, b) => b.length - a.length);
 }
-/** One JSON object per line: info on stdout, errors on stderr, secrets replaced by `[redacted]`. */
+/**
+ * One JSON object per line: info on stdout, warnings and errors on stderr, secrets replaced by
+ * `[redacted]`.
+ */
 function createLogger(io) {
     const secrets = secretsIn(io.env);
     const write = (stream, level, event, fields = {}) => {
@@ -267,6 +345,7 @@ function createLogger(io) {
     };
     return {
         info: (event, fields) => write(io.stdout, 'info', event, fields),
+        warn: (event, fields) => write(io.stderr, 'warn', event, fields),
         error: (event, fields) => write(io.stderr, 'error', event, fields),
     };
 }
@@ -348,16 +427,90 @@ async function databaseReachable(sql) {
     }
 }
 /**
- * Whether the dashboard's allowlist lets a tenant act: every tenant when there is no dashboard or it
- * allows everyone, and a `github:<id>` tenant only while that id is listed.
+ * `GET <path>` answers the metrics to `Authorization: Bearer <token>`, before the request limits:
+ * a scrape is in memory and names no tenant. Anything else goes on to `target`.
+ */
+function serveMetrics(target, metrics, path, token) {
+    const expected = createHash('sha256').update(token).digest();
+    return {
+        fetch(request, connection) {
+            if (new URL(request.url).pathname !== path)
+                return target.fetch(request, connection);
+            // The scheme is case-insensitive (RFC 9110); the token is compared as digests, in constant time.
+            const presented = /^bearer +(\S+) *$/i.exec(request.headers.get('authorization') ?? '')?.[1] ?? '';
+            const given = createHash('sha256').update(presented).digest();
+            if (!timingSafeEqual(given, expected)) {
+                metrics.refusedScrape();
+                return Promise.resolve(new Response('Unauthorized\n', {
+                    status: 401,
+                    headers: { 'Content-Type': 'text/plain; charset=utf-8', 'WWW-Authenticate': 'Bearer' },
+                }));
+            }
+            if (request.method !== 'GET' && request.method !== 'HEAD') {
+                return Promise.resolve(new Response(null, { status: 405, headers: { Allow: 'GET, HEAD' } }));
+            }
+            return Promise.resolve(new Response(request.method === 'HEAD' ? null : metrics.render(), {
+                headers: {
+                    'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+                    'Cache-Control': 'no-store',
+                },
+            }));
+        },
+        ...(target.shutdown ? { shutdown: () => target.shutdown?.() } : {}),
+    };
+}
+/**
+ * Whether the dashboard's allowlists let a tenant act: a `github-org:<id>` tenant only while
+ * SLOTLOCK_DASHBOARD_ORGS lists that organization, wherever the dashboard runs; otherwise every
+ * tenant when there is no dashboard or it allows everyone, and a `github:<id>` tenant only while
+ * that id is listed.
  */
 function dashboardAllows(config, tenantRef) {
+    const orgId = /^github-org:(\d+)$/.exec(tenantRef)?.[1];
+    if (orgId !== undefined)
+        return config.organizations?.includes(orgId) === true;
     const users = config.dashboard?.allowedUsers;
     if (users === undefined || users === '*')
         return true;
     const githubId = /^github:(\d+)$/.exec(tenantRef)?.[1];
     return githubId === undefined || users.includes(githubId);
 }
+function serveTenantLimits(caps) {
+    return {
+        resources: SERVE_MAX_TENANT_RESOURCES,
+        holds: caps.tenant_holds,
+        reservations: caps.tenant_reservations,
+        events: caps.tenant_events,
+        coverage: caps.tenant_coverage,
+    };
+}
+/**
+ * The store `serve` answers requests from. Every surface writes through it, so its tenant limits
+ * bound what any key can add, and its transaction limits what one tenant holds of the shared pool.
+ */
+export function createSlotlockServeStore(sql, caps, availability = [], retentionDays) {
+    return createSlotlockStore(sql, {
+        ...(retentionDays !== undefined ? { retentionDays } : {}),
+        defaultAvailabilityRules: availability,
+        tenantLimits: serveTenantLimits(caps),
+        maxTenantTransactions: caps.tenant_transactions,
+        maxHoldsPerHolder: caps.holder_holds,
+        maxHeldHoursPerHolder: caps.holder_held_hours,
+        tenantLockTimeoutMs: SERVE_LOCK_TIMEOUT_MS,
+    });
+}
+/**
+ * The store maintenance writes through, `serve`'s and `maintain`'s: the same tenant and per-holder
+ * limits as requests, so a waitlist offer is a hold like any other.
+ */
+export function createSlotlockMaintenanceStore(sql, caps, options = {}) {
+    return createSlotlockStore(sql, {
+        ...options,
+        tenantLimits: serveTenantLimits(caps),
+        maxHoldsPerHolder: caps.holder_holds,
+        maxHeldHoursPerHolder: caps.holder_held_hours,
+    });
+}
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export async function startSlotlockServer(config, log) {
     const sql = connect(config.databaseUrl, POOL_SIZE);
@@ -376,6 +529,9 @@ export async function startSlotlockServer(config, log) {
         if (!schema?.present) {
             throw Object.assign(new Error('The slotlock schema is missing: run `slotlock migrate` or `slotlock serve --migrate`'), { code: 'schema_missing' });
         }
+        // Migrated by another release: an older schema needs this release's migrate first, and a newer
+        // one has tables and rules this release's code does not know.
+        await assertSlotlockSchemaCurrent(sql);
         // A deployment run statement by statement lifts forced row-level security for its data steps
         // and, stopped part way, leaves it lifted until the next one puts it back. The owning role then
         // reads every tenant's rows: refuse to serve until then.
@@ -400,9 +556,27 @@ export async function startSlotlockServer(config, log) {
                 }
             }
         }
-        const store = createSlotlockStore(sql);
+        if (config.confirmationSecret !== undefined) {
+            // Accepted confirmations are recorded once each (0.3.1); an older schema cannot hold them.
+            const [recordable] = await sql `
+        SELECT EXISTS (
+          SELECT 1 FROM pg_catalog.pg_constraint
+           WHERE conname = 'slotlock_dashboard_tokens_kind_valid'
+             AND conrelid = to_regclass('slotlock.dashboard_tokens')
+             AND pg_catalog.pg_get_constraintdef(oid) LIKE '%confirmation%'
+        ) AND has_function_privilege(to_regprocedure(${SLOTLOCK_DASHBOARD_FUNCTIONS[0]}), 'EXECUTE') AS ready`;
+            if (!recordable?.ready) {
+                throw Object.assign(new Error('SLOTLOCK_CONFIRM_WRITES records each accepted confirmation, which this schema cannot: run `slotlock migrate` (or `slotlock serve --migrate`) with this release'), { code: 'schema_outdated' });
+            }
+        }
+        const { caps } = config.limits;
+        const store = createSlotlockServeStore(sql, caps, config.availability, config.retentionDays);
+        const retention = config.retentionDays !== undefined ? { retentionDays: config.retentionDays } : {};
         const publicUrl = new URL(config.publicUrl);
-        const authenticateKey = createSlotlockApiKeyAuthenticator(createSlotlockApiKeyStore(sql));
+        const authenticateKey = createSlotlockApiKeyAuthenticator(createSlotlockApiKeyStore(sql), {
+            maxConcurrentLookups: caps.key_lookups,
+            maxWaitingLookups: caps.key_lookup_queue,
+        });
         const authenticateToken = config.authToken === undefined
             ? undefined
             : // Read and write, never admin: this is the token the docs put in agents' configuration,
@@ -414,13 +588,34 @@ export async function startSlotlockServer(config, log) {
                 });
         // Set once the listener is up; the authenticator tells it which tenants this server serves.
         let maintenance;
-        const agentServer = createSlotlockAgentServer({
-            publicBaseUrl: config.publicUrl,
-            // readPublicUrl admits plain HTTP only on a loopback host, which is all this permits anyway.
-            allowInsecureLocalhost: publicUrl.protocol === 'http:',
-            backend: createSlotlockStoreAgentBackend(store, {
-                availabilityRules: async () => config.availability.map((rule) => ({ ...rule })),
-            }),
+        let webhooks;
+        const basePath = publicUrl.pathname.replace(/\/$/, '');
+        const metrics = config.metricsToken === undefined
+            ? undefined
+            : createSlotlockMetrics({
+                version: slotlockPackageVersion(),
+                ...(process.versions.tz ? { tzdata: process.versions.tz } : {}),
+            });
+        const limits = createSlotlockRequestLimits({
+            limits: config.limits,
+            ...(config.sharedLimits
+                ? {
+                    shared: {
+                        // Keyed by a digest: the table keeps no tenant name.
+                        take: async (bucket, rate) => {
+                            const digest = createHash('sha256').update(bucket).digest('hex');
+                            const [row] = await sql `
+                  SELECT slotlock.take_rate_token(${digest}, ${rate.perSecond}, ${rate.burst}) AS taken`;
+                            return row?.taken === true;
+                        },
+                    },
+                }
+                : {}),
+            ...(config.trustedProxyHeader !== undefined
+                ? { trustedProxyHeader: config.trustedProxyHeader }
+                : {}),
+            basePath,
+            signInPaths: config.dashboard ? ['/dashboard/sign-in', '/dashboard/callback'] : [],
             // The token is compared in constant time first; only then is a key looked up. A person the
             // dashboard no longer allows loses their keys with their session.
             authenticate: async (request) => {
@@ -430,12 +625,51 @@ export async function startSlotlockServer(config, log) {
                 maintenance?.touch(principal.tenantRef);
                 return principal;
             },
-            authorize: async ({ principal, operation }) => authorizeSlotlockServeOperation({ principal, operation }),
-            health: async () => (await databaseReachable(sql))
-                ? { ready: true, checks: ['database'] }
-                : { ready: false, checks: ['database_unreachable'] },
+            // Counts and pseudonyms only: never an address, a credential or a tenant.
+            onRefusals: (counts) => {
+                metrics?.refusals(counts);
+                log.info('refusals', { ...counts });
+            },
+            // Behind a proxy without the setting, every client shares the proxy's address budget.
+            onIgnoredClientField: (field) => log.warn('client_address_field_ignored', { field, setting: 'SLOTLOCK_TRUSTED_PROXY_HEADER' }),
+        });
+        let health;
+        const agentServer = createSlotlockAgentServer({
+            publicBaseUrl: config.publicUrl,
+            // readPublicUrl admits plain HTTP only on a loopback host, which is all this permits anyway.
+            allowInsecureLocalhost: publicUrl.protocol === 'http:',
+            backend: createSlotlockStoreAgentBackend(store, {
+                availabilityRules: async () => config.availability.map((rule) => ({ ...rule })),
+            }),
+            authenticate: limits.authenticate,
+            consumeRateLimit: limits.consumeRateLimit,
+            // A write that may expand a recurring series also waits for one of a few slots, so one
+            // tenant's expansions cannot hold the event loop from every other tenant's requests.
+            authorize: async ({ principal, operation, input }) => {
+                if (!authorizeSlotlockServeOperation({ principal, operation }))
+                    return false;
+                await limits.admit({ principal, operation, input });
+                return true;
+            },
+            subscriptions: {
+                maxTotal: caps.subscriptions,
+                maxPerTenant: caps.tenant_subscriptions,
+                maxPerPrincipal: slotlockKeySubscriptions(caps),
+            },
+            health: async () => {
+                if (!health || performance.now() - health.at > HEALTH_RESULT_MS) {
+                    health = { at: performance.now(), ready: databaseReachable(sql) };
+                }
+                return (await health.ready)
+                    ? { ready: true, checks: ['database'] }
+                    : { ready: false, checks: ['database_unreachable'] };
+            },
             // Outcomes and counts only: the server never reports arguments or identities.
-            onEvent: ({ type, ...fields }) => log.info(type, snakeCaseKeys(fields)),
+            onEvent: (event) => {
+                metrics?.event(event);
+                const { type, ...fields } = event;
+                log.info(type, snakeCaseKeys(fields));
+            },
             // What an agent sees only as internal_error: the operation and the error's message and code,
             // never the arguments or the request, with every configured secret redacted.
             onError: (error, { operation }) => log.error('agent_error', { operation, ...describeError(error) }),
@@ -447,7 +681,12 @@ export async function startSlotlockServer(config, log) {
                         backend: createSlotlockStoreApplicationBackend(store, {
                             maxTenantResources: SERVE_MAX_TENANT_RESOURCES,
                         }),
-                        authorize: async ({ principal }) => principal.scopes?.includes(SLOTLOCK_APPLICATION_SCOPE) === true,
+                        authorize: async ({ principal, operation, input }) => {
+                            if (principal.scopes?.includes(SLOTLOCK_APPLICATION_SCOPE) !== true)
+                                return false;
+                            await limits.admit({ principal, operation, input });
+                            return true;
+                        },
                     },
                 }
                 : {}),
@@ -456,6 +695,7 @@ export async function startSlotlockServer(config, log) {
                     confirmation: {
                         operations: config.confirmWrites,
                         secrets: [config.confirmationSecret],
+                        consumeAcceptance: createSlotlockAcceptanceRecords(sql),
                     },
                 }
                 : {}),
@@ -470,32 +710,75 @@ export async function startSlotlockServer(config, log) {
                 },
                 sessionSecret: config.dashboard.sessionSecret,
                 allowedUsers: config.dashboard.allowedUsers,
+                ...(config.dashboard.name ? { name: config.dashboard.name } : {}),
+                ...(config.dashboard.organizations
+                    ? { organizations: config.dashboard.organizations }
+                    : {}),
                 keys: createSlotlockApiKeyStore(sql),
                 resources: createSlotlockDashboardResources(store),
                 state: createSlotlockDashboardState(sql),
                 availability: config.availability,
+                clientAddress: (request) => limits.clientAddress(request),
                 onError: (error) => log.error('dashboard_error', describeError(error)),
             });
-        const target = dashboard
+        const target = limits.serve(dashboard
             ? {
                 fetch: (request) => dashboard.handles(request) ? dashboard.fetch(request) : agentServer.fetch(request),
                 shutdown: () => agentServer.shutdown(),
             }
-            : agentServer;
-        const listener = createSlotlockNodeServer(target, {
+            : agentServer);
+        const served = metrics && config.metricsToken !== undefined
+            ? serveMetrics(target, metrics, `${basePath}/metrics`, config.metricsToken)
+            : target;
+        const listener = createSlotlockNodeServer(served, {
             requestOrigin: publicUrl.origin,
             onError: (error, phase) => log.error('http_error', { phase, ...describeError(error) }),
         });
         const address = await listener.listen({ host: config.host, port: config.port });
         maintenance = startSlotlockMaintenance({
-            store,
+            // One tenant at a time, and its long passes may wait on a request's locks for longer.
+            store: createSlotlockMaintenanceStore(sql, caps, retention),
             sql,
             tenants: [config.tenantRef],
             intervalMs: SERVE_MAINTENANCE_INTERVAL_MS,
             // Counts only, never the tenant.
-            onPass: (result) => log.info('maintenance', { ...result }),
+            onPass: (result) => {
+                metrics?.maintenance(result);
+                log.info('maintenance', { ...result });
+            },
             onError: (error) => log.error('maintenance_failed', describeError(error)),
         });
+        if (config.webhooks !== 'off') {
+            const deliveryStore = createSlotlockStore(sql, retention);
+            const send = createSlotlockWebhookSender({ allowPrivateNetworks: config.webhooks === 'private' });
+            webhooks = startSlotlockWebhookDelivery({
+                // The tenants with a webhook, from the database: a restarted server finds them all.
+                tenants: async () => {
+                    const tenants = [];
+                    for (;;) {
+                        const page = await sql `
+              SELECT slotlock.webhook_tenants(${tenants.at(-1) ?? null}::text) AS tenant`;
+                        tenants.push(...page.map(({ tenant }) => tenant));
+                        if (page.length < 1_000)
+                            return tenants;
+                    }
+                },
+                deliver: (tenantRef) => deliverSlotlockWebhooks({
+                    tenantRef,
+                    send,
+                    feed: {
+                        claimWebhookDeliveries: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.claimWebhookDeliveries(params)),
+                        settleWebhookDelivery: (params) => deliveryStore.withTenant(tenantRef, (tenant) => tenant.settleWebhookDelivery(params)),
+                    },
+                }),
+                // Counts only, never the tenant or a URL.
+                onPass: (_tenant, result) => {
+                    metrics?.webhooks(result);
+                    log.info('webhooks', { ...result });
+                },
+                onError: (error) => log.error('webhooks_failed', describeError(error)),
+            });
+        }
         log.info('listening', {
             address: address.origin,
             mcp: `${config.publicUrl}/mcp`,
@@ -506,13 +789,25 @@ export async function startSlotlockServer(config, log) {
             confirm_writes: config.confirmWrites,
             availability_rules: config.availability.length,
             rest: config.restApi ? `${config.publicUrl}/openapi.json` : null,
+            webhooks: config.webhooks,
+            shared_limits: config.sharedLimits,
+            tzdata: process.versions.tz ?? null,
             maintenance_interval_minutes: SERVE_MAINTENANCE_INTERVAL_MS / 60_000,
+            limits: {
+                ...Object.fromEntries(Object.entries(config.limits.rates).map(([name, rate]) => [name, formatSlotlockRate(rate)])),
+                ...caps,
+                // What a key may hold, which is below key_subscriptions when the tenant's cap is lower.
+                key_subscriptions: slotlockKeySubscriptions(caps),
+            },
+            client_address: config.trustedProxyHeader ?? 'socket',
         });
         return {
             address,
             async close() {
                 const result = await listener.close();
+                limits.close();
                 await maintenance?.close();
+                await webhooks?.close();
                 await sql.end({ timeout: 5 });
                 return result;
             },
@@ -571,8 +866,8 @@ function hoursLine(resource) {
         hours: resource.availabilityRules ?? null,
     })}\n`;
 }
-/** Every resource of the tenant, a page at a time. */
-async function tenantResources(store, tenantRef) {
+/** Every resource of the tenant in use (with `includeArchived`, every one), a page at a time. */
+async function tenantResources(store, tenantRef, includeArchived = false) {
     const all = [];
     let after;
     for (;;) {
@@ -580,6 +875,7 @@ async function tenantResources(store, tenantRef) {
             tenantRef,
             limit: RESOURCE_PAGE_SIZE,
             ...(after !== undefined ? { after } : {}),
+            ...(includeArchived ? { includeArchived } : {}),
         }));
         all.push(...page);
         after = page.at(-1)?.id;
@@ -626,6 +922,118 @@ async function runHours(config, out, target, rules) {
         await sql.end({ timeout: 5 });
     }
 }
+/**
+ * `rules set|clear`: set or clear (`null`) the booking rules of the tenant's resource named by id,
+ * else by reference, and print it. Returns false when no resource has that name.
+ */
+async function runRules(config, out, name, rules) {
+    const sql = connect(config.databaseUrl, 1);
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        const resources = await tenantResources(store, tenantRef);
+        const named = resources.find((resource) => resource.id === name) ??
+            resources.find((resource) => resource.externalRef === name);
+        if (!named)
+            return false;
+        const updated = await store.withTenant(tenantRef, (tenant) => tenant.setResourceBookingRules({ tenantRef, id: named.id, rules }));
+        if (!updated)
+            return false;
+        out.write(`${JSON.stringify({
+            id: updated.id,
+            external_ref: updated.externalRef,
+            booking_rules: updated.bookingRules ?? null,
+        })}\n`);
+        return true;
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
+/** A resource as `resource archive` and `resource restore` print it. */
+function resourceStateLine(resource) {
+    return `${JSON.stringify({
+        id: resource.id,
+        external_ref: resource.externalRef,
+        timezone: resource.timezone,
+        visibility: resource.visibility ?? 'shared',
+        archived_at: resource.archivedAt?.toISOString() ?? null,
+    })}\n`;
+}
+/**
+ * `resource archive|restore|delete`: the tenant's resource named by id, else by reference, archived
+ * ones included. Returns false when no resource has that name, and `in_use` when a delete is
+ * refused because something on the resource has not ended.
+ */
+async function changeResource(config, out, name, action) {
+    const sql = connect(config.databaseUrl, 1);
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        const resources = await tenantResources(store, tenantRef, true);
+        // An id first: another resource's reference may spell it.
+        const named = resources.find((resource) => resource.id === name) ??
+            resources.find((resource) => resource.externalRef === name);
+        if (!named)
+            return false;
+        const id = named.id;
+        if (action === 'delete') {
+            const result = await store.withTenant(tenantRef, (tenant) => tenant.deleteResource({ tenantRef, id }));
+            if (!result.ok)
+                return 'in_use';
+            if (!result.deleted)
+                return false;
+            out.write(`${JSON.stringify({ id, external_ref: named.externalRef, deleted: true })}\n`);
+            return true;
+        }
+        const changed = await store.withTenant(tenantRef, (tenant) => action === 'archive'
+            ? tenant.archiveResource({ tenantRef, id })
+            : tenant.restoreResource({ tenantRef, id }));
+        if (!changed)
+            return false;
+        out.write(resourceStateLine(changed));
+        return true;
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
+/**
+ * `tenant status|suspend|unsuspend|erase` for SLOTLOCK_TENANT. Suspending and lifting a suspension
+ * are the deployment role's alone, so they connect as SLOTLOCK_MIGRATE_DATABASE_URL when it is set;
+ * the serving role reads a suspension and may erase.
+ */
+async function runTenantCommand(config, out, action, reason) {
+    const owner = action === 'suspend' || action === 'unsuspend';
+    const sql = connect(owner ? (config.migrateDatabaseUrl ?? config.databaseUrl) : config.databaseUrl, 1);
+    try {
+        const store = createSlotlockStore(sql);
+        const tenantRef = config.tenantRef;
+        let line;
+        if (action === 'status') {
+            line = { tenant: tenantRef, suspended: await store.isTenantSuspended({ tenantRef }) };
+        }
+        else if (action === 'suspend') {
+            const { suspended } = await store.suspendTenant({
+                tenantRef,
+                ...(reason !== undefined ? { reason } : {}),
+            });
+            line = { tenant: tenantRef, suspended: true, changed: suspended };
+        }
+        else if (action === 'unsuspend') {
+            const { unsuspended } = await store.unsuspendTenant({ tenantRef });
+            line = { tenant: tenantRef, suspended: false, changed: unsuspended };
+        }
+        else {
+            const erased = await store.eraseTenant({ tenantRef });
+            line = { tenant: tenantRef, total: erased.total, rows: erased.rows };
+        }
+        out.write(`${JSON.stringify(line)}\n`);
+    }
+    finally {
+        await sql.end({ timeout: 5 });
+    }
+}
 /** One key as `key create`, `key list` and `key revoke` print it: never the digest. */
 function apiKeyLine(apiKey, key) {
     return `${JSON.stringify({
@@ -656,12 +1064,23 @@ function parseKeyScopes(value) {
  * `maintain`: maintenance passes for the tenant until nothing is left, under the tenant's lock, so
  * it never repeats what a server is doing. Null when another server holds the lock.
  */
-async function maintainTenant(config) {
+async function maintainTenant(config, caps) {
     const sql = connect(config.databaseUrl, 2);
     try {
-        const store = createSlotlockStore(sql);
+        const store = createSlotlockMaintenanceStore(sql, caps, config.retentionDays !== undefined ? { retentionDays: config.retentionDays } : {});
         const total = await withSlotlockMaintenanceLock(sql, config.tenantRef, async () => {
-            const sum = { extended: 0, conflicts: 0, refused: 0, pruned: 0, capped: true, passes: 0 };
+            const sum = {
+                extended: 0,
+                conflicts: 0,
+                refused: 0,
+                pruned: 0,
+                zoneShifts: 0,
+                staleSources: 0,
+                noShows: 0,
+                waitlistOffers: 0,
+                capped: true,
+                passes: 0,
+            };
             while (sum.capped && sum.passes < MAINTAIN_MAX_PASSES) {
                 const pass = await maintainSlotlockTenant(store, config.tenantRef);
                 sum.passes += 1;
@@ -669,9 +1088,15 @@ async function maintainTenant(config) {
                 sum.conflicts += pass.conflicts;
                 sum.refused += pass.refused;
                 sum.pruned += pass.pruned;
-                // A capped pass that got nowhere met only series it cannot extend: another would too.
+                sum.zoneShifts += pass.zoneShifts;
+                sum.staleSources += pass.staleSources;
+                sum.noShows += pass.noShows;
+                sum.waitlistOffers += pass.waitlistOffers;
+                // A capped pass that got nowhere met only series it cannot extend. While its roll stopped
+                // before the series it had put back, the next pass meets new ones (and perhaps a healthy
+                // one); once it reached them, another pass would meet them again.
                 sum.capped = pass.capped;
-                if (pass.capped && pass.extended + pass.pruned === 0)
+                if (pass.capped && pass.extended + pass.pruned === 0 && !pass.rollPending)
                     break;
             }
             return sum;
@@ -731,12 +1156,22 @@ Commands:
   resource add <ref> [--timezone <IANA zone>]
                            Create a calendar resource (a car, room, person or machine)
   resource list            Print the tenant's resources, one JSON object per line
+  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and
+                           no longer listed; what is on it stays
+  resource restore <ref>   Put an archived resource back in use
+  resource delete <ref>    Delete a resource and its history; refused while a booking, hold
+                           or event on it has not ended
   hours show [--resource <ref>]
                            Print each resource's bookable hours (null: the server's)
   hours set <json> (--resource <ref> | --all)
                            Give one resource, or every one, weekly hours of its own; [] closes
   hours clear (--resource <ref> | --all)
                            Hand one resource, or every one, back to the server's hours
+  rules set <json> --resource <ref>
+                           Set what a booking on the resource must satisfy, like
+                           {"minNoticeMinutes":120,"slotStepMinutes":30,"turnaroundMinutes":30,"enforceHours":true}
+  rules clear --resource <ref>
+                           Remove the resource's booking rules
   key create <name> [--scope read,write,admin] [--expires-in-days <n>]
                            Create an API key for the tenant (default scope read,write, no
                            expiry; admin adds the application API) and print it once; only its
@@ -745,6 +1180,15 @@ Commands:
   key rotate <id>          Give an active key a new secret and print it once; the old one stops
                            working at once, and the key keeps its id and what it booked
   key revoke <id>          Revoke one of the tenant's API keys at once
+  tenant status            Print whether the tenant is suspended
+  tenant suspend [--reason <text>]
+                           Suspend the tenant: it may read, and writes nothing; its keys get
+                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:
+                           only the schema owner suspends)
+  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)
+  tenant erase --confirm <tenant>
+                           Delete everything the tenant has, its API keys included, for good;
+                           --confirm repeats SLOTLOCK_TENANT
   healthcheck              Exit 0 when the local server reports ready
 
 Options:
@@ -755,21 +1199,59 @@ Environment:
   DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve
                                  refuses a superuser or a role with BYPASSRLS
   SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)
-  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with every scope,
-                                 32+ random characters (serve); API keys work with or without it
-  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve)
-  SLOTLOCK_CONFIRM_WRITES        all (default), none, or a comma-separated list of write tools
+  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write
+                                 access (never admin), 32+ random characters (serve); API keys
+                                 work with or without it
+  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;
+                                 required when SLOTLOCK_CONFIRM_WRITES is not none)
+  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+
+                                 random characters (serve; off without it)
+  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools
+                                 that wait for a person (MCP 2026-07-28 form elicitation; refused
+                                 with confirmation_required on REST, A2A and older MCP)
   SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)
   SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default "default")
   SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)
   SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and
                                  the application API for admin keys, described at /openapi.json;
                                  off: MCP and A2A only
+  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,
+                                 and retired answers (never under 30) (1-3650, default 30;
+                                 serve and maintain)
+  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the
+                                 database, so N servers allow a tenant its rate once; off (default):
+                                 each server keeps its own
+  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,
+                                 never to a private network address; private: those too, for
+                                 testing; off: keep the change feed, send nothing
+  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:
+                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,
+                                 every request per client, before any key lookup), key_read,
+                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),
+                                 global_read (500/s:1000), global_write (50/s:100), app_read
+                                 (20/s:40) and app_write (5/s:20) per tenant for the
+                                 application API, sign_in (20/m:20); counts for
+                                 tenant_series_writes and series_writes
+                                 (1: writes that may expand a recurring series at once),
+                                 maintenance_runs (1: application API maintenance runs at once),
+                                 subscriptions (256), tenant_subscriptions (16),
+                                 key_subscriptions (4, and fewer than tenant_subscriptions),
+                                 key_lookups (2), key_lookup_queue (256),
+                                 tenant_transactions (2: one tenant's database transactions at
+                                 once, of the pool's 10); what one tenant may store:
+                                 tenant_holds (10000), tenant_reservations, tenant_events and
+                                 tenant_coverage (100000), holder_holds (20) and
+                                 holder_held_hours (2160), which maintain keeps too
+  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,
+                                 such as CF-Connecting-IP (default: the connection's address);
+                                 set it only when every request comes through that proxy
   SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID
                                  of a GitHub OAuth app with callback .../dashboard/callback
   SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)
   SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)
   SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)
+  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant
+  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)
   HOST                           Listen address (default 127.0.0.1)
   PORT                           Listen port (default 8080)
 
@@ -806,7 +1288,11 @@ export async function runSlotlockCli(argv, io) {
         io.stderr.write(SLOTLOCK_CLI_HELP);
         return 2;
     }
-    const subcommand = command === 'resource' || command === 'key' || command === 'hours'
+    const subcommand = command === 'resource' ||
+        command === 'key' ||
+        command === 'hours' ||
+        command === 'rules' ||
+        command === 'tenant'
         ? `${command} ${operands[0] ?? ''}`.trim()
         : command;
     const expectedOperands = {
@@ -816,6 +1302,13 @@ export async function runSlotlockCli(argv, io) {
         healthcheck: 0,
         'resource add': 2,
         'resource list': 1,
+        'resource archive': 2,
+        'resource restore': 2,
+        'resource delete': 2,
+        'tenant status': 1,
+        'tenant suspend': 1,
+        'tenant unsuspend': 1,
+        'tenant erase': 1,
         'key create': 2,
         'key list': 1,
         'key rotate': 2,
@@ -823,6 +1316,8 @@ export async function runSlotlockCli(argv, io) {
         'hours show': 1,
         'hours set': 2,
         'hours clear': 1,
+        'rules set': 2,
+        'rules clear': 1,
     };
     const expected = expectedOperands[subcommand];
     if (expected === undefined)
@@ -839,11 +1334,36 @@ export async function runSlotlockCli(argv, io) {
             return usage(`--${option} applies only to key create`);
         }
     }
+    if (values.reason !== undefined && subcommand !== 'tenant suspend') {
+        return usage('--reason applies only to tenant suspend');
+    }
+    if (values.confirm !== undefined && subcommand !== 'tenant erase') {
+        return usage('--confirm applies only to tenant erase');
+    }
+    if (subcommand === 'tenant erase' && values.confirm === undefined) {
+        return usage('tenant erase needs --confirm <tenant>, the tenant it erases (SLOTLOCK_TENANT)');
+    }
     if (values.all && subcommand !== 'hours set' && subcommand !== 'hours clear') {
         return usage('--all applies only to hours set and hours clear');
     }
-    if (values.resource !== undefined && !subcommand.startsWith('hours ')) {
-        return usage('--resource applies only to hours commands');
+    if (values.resource !== undefined &&
+        !subcommand.startsWith('hours ') &&
+        !subcommand.startsWith('rules ')) {
+        return usage('--resource applies only to hours and rules commands');
+    }
+    if (subcommand.startsWith('rules ') && values.resource === undefined) {
+        return usage(`${subcommand} needs --resource <ref>`);
+    }
+    let bookingRules = null;
+    if (subcommand === 'rules set') {
+        try {
+            bookingRules = parseBookingRules(JSON.parse(operands[1]));
+        }
+        catch (error) {
+            return usage(error instanceof SyntaxError
+                ? 'rules must be a JSON object like {"minNoticeMinutes":120,"slotStepMinutes":30}'
+                : error.message);
+        }
     }
     if ((subcommand === 'hours set' || subcommand === 'hours clear') &&
         (values.resource === undefined) === (values.all !== true)) {
@@ -896,7 +1416,7 @@ export async function runSlotlockCli(argv, io) {
                 return 0;
             }
             case 'maintain': {
-                const result = await maintainTenant(readSlotlockDatabaseConfig(io.env));
+                const result = await maintainTenant(readSlotlockDatabaseConfig(io.env), readLimits(io.env).caps);
                 if (!result) {
                     io.stderr.write('slotlock: another server is maintaining this tenant now; nothing to do\n');
                     return 0;
@@ -913,6 +1433,45 @@ export async function runSlotlockCli(argv, io) {
             case 'resource list':
                 await listResources(readSlotlockDatabaseConfig(io.env), io.stdout);
                 return 0;
+            case 'resource archive':
+            case 'resource restore':
+            case 'resource delete': {
+                const changed = await changeResource(readSlotlockDatabaseConfig(io.env), io.stdout, operands[1], subcommand.slice('resource '.length));
+                if (changed === 'in_use') {
+                    io.stderr.write('slotlock: a booking, hold or calendar event on that resource has not ended; cancel or move it first, or archive the resource\n');
+                    return 1;
+                }
+                if (!changed) {
+                    io.stderr.write('slotlock: no resource with that reference or id in this tenant\n');
+                    return 1;
+                }
+                return 0;
+            }
+            case 'tenant status':
+            case 'tenant suspend':
+            case 'tenant unsuspend':
+            case 'tenant erase': {
+                const config = readSlotlockDatabaseConfig(io.env);
+                // The tenant named twice, so erasing the one SLOTLOCK_TENANT happens to name is deliberate.
+                if (subcommand === 'tenant erase' && values.confirm !== config.tenantRef) {
+                    return usage('--confirm must repeat SLOTLOCK_TENANT, the tenant tenant erase deletes');
+                }
+                try {
+                    await runTenantCommand(config, io.stdout, subcommand.slice('tenant '.length), values.reason);
+                }
+                catch (error) {
+                    const code = error?.code;
+                    if (code === 'tenant_suspension_not_permitted') {
+                        io.stderr.write('slotlock: only the schema owner suspends a tenant or lifts a suspension; set SLOTLOCK_MIGRATE_DATABASE_URL to its URL\n');
+                        return 1;
+                    }
+                    if (code === 'invalid_suspension_reason') {
+                        return usage('--reason must be 1-500 characters without control characters');
+                    }
+                    throw error;
+                }
+                return 0;
+            }
             case 'hours show':
             case 'hours set':
             case 'hours clear': {
@@ -928,6 +1487,15 @@ export async function runSlotlockCli(argv, io) {
                 }
                 return 0;
             }
+            case 'rules set':
+            case 'rules clear': {
+                const found = await runRules(readSlotlockDatabaseConfig(io.env), io.stdout, values.resource, bookingRules);
+                if (!found) {
+                    io.stderr.write('slotlock: no resource with that reference or id in this tenant\n');
+                    return 1;
+                }
+                return 0;
+            }
             case 'key create': {
                 const config = readSlotlockDatabaseConfig(io.env);
                 const created = await withApiKeys(config, (keys) => keys.create({
@@ -996,6 +1564,8 @@ function parseCliArguments(argv) {
             'expires-in-days': { type: 'string' },
             resource: { type: 'string' },
             all: { type: 'boolean' },
+            reason: { type: 'string' },
+            confirm: { type: 'string' },
             help: { type: 'boolean', short: 'h' },
             version: { type: 'boolean', short: 'v' },
         },