slotlock 0.6.2 → 0.6.3

package/rate-limit.js

@@ -11,11 +11,12 @@
 // t=<seconds>` and `"<policy>";q=<quota>;w=<window seconds>`, or `qu="concurrent-requests"` for a
 // cap on requests at once. Retry-After is never earlier than the end of the effective window (§6).
 import { AsyncLocalStorage } from 'node:async_hooks';
-import { createHmac, randomBytes } from 'node:crypto';
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 import { isIP } from 'node:net';
 import { SLOTLOCK_MCP_PROTOCOL_VERSION, SLOTLOCK_MCP_RATE_LIMITED_ERROR_CODE, SlotlockAgentOperationError, slotlockAgentOperationScope, } from './agent-server.js';
 import { slotlockBearerCredential } from './api-keys.js';
 import { SLOTLOCK_APPLICATION_SCOPE } from './application-api.js';
+import { SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD, } from './config.js';
 import { SLOTLOCK_APPLICATION_REST_ROUTES, matchSlotlockRestRoute } from './rest-api.js';
 /** Keys one policy remembers; past this, the least recently used tenth is dropped at once. */
 const MAX_BUCKET_KEYS = 100_000;
@@ -88,9 +89,23 @@ export function slotlockClientNetwork(key) {
     const prefix = /^([0-9a-f]{1,4}:[0-9a-f]{1,4}:[0-9a-f]{1,4}):[0-9a-f]{1,4}::\/64$/.exec(key);
     return prefix ? `${prefix[1]}::/48` : key;
 }
-/** The client a request is counted as: the trusted field's last address, else the connection's. */
-function clientOf(request, connection, trustedField) {
-    if (trustedField !== undefined) {
+const sha256 = (value) => createHash('sha256').update(value, 'utf8').digest();
+/**
+ * Whether the request carries the proxy's secret. Compared as SHA-256 digests in constant time, so
+ * neither the time taken nor a length tells how much of a guess matched. A repeated field arrives
+ * joined with a comma and so never matches.
+ */
+function provenByProxy(request, secretDigest) {
+    const presented = request.headers.get(SLOTLOCK_TRUSTED_PROXY_PROOF_FIELD);
+    return presented !== null && timingSafeEqual(sha256(presented), secretDigest);
+}
+/**
+ * The client a request is counted as: the trusted field's last address, else the connection's.
+ * With a proxy secret, the field is believed only beside the proof.
+ */
+function clientOf(request, connection, trustedField, secretDigest) {
+    const believed = secretDigest === undefined || provenByProxy(request, secretDigest);
+    if (trustedField !== undefined && believed) {
         // A proxy appends to a list field (X-Forwarded-For), so the last entry is the one it wrote.
         const claimed = request.headers.get(trustedField)?.split(',').at(-1);
         const key = claimed === undefined ? null : slotlockClientKey(claimed);
@@ -169,7 +184,7 @@ function concurrencyFields(name, cap) {
     };
 }
 /** Token buckets of one policy, one per key, refilled lazily. */
-function bucketsFor(rate, now) {
+function bucketsFor(rate) {
     const buckets = new Map();
     const refill = (bucket, at) => {
         bucket.tokens = Math.min(rate.burst, bucket.tokens + ((at - bucket.at) / 1_000) * rate.perSecond);
@@ -211,7 +226,7 @@ export function createSlotlockRateLimiter(rate, now = () => performance.now()) {
     if (!(rate.perSecond > 0) || !(rate.burst >= 1)) {
         throw new Error('Slotlock rate limiter needs a positive rate and a burst of at least 1');
     }
-    const buckets = bucketsFor(rate, now);
+    const buckets = bucketsFor(rate);
     return {
         take(key) {
             const bucket = buckets.get(key, now());
@@ -416,11 +431,12 @@ export function createSlotlockRequestLimits(options) {
     const policies = new Map();
     for (const [name, rate] of Object.entries(rates)) {
         if (rate !== null)
-            policies.set(name, { policy: { name, rate }, buckets: bucketsFor(rate, now) });
+            policies.set(name, { policy: { name, rate }, buckets: bucketsFor(rate) });
     }
     const states = new AsyncLocalStorage();
     const looked = new WeakMap();
     const addresses = new WeakMap();
+    const proxySecretDigest = options.trustedProxySecret === undefined ? undefined : sha256(options.trustedProxySecret);
     const gates = {
         series: {
             gate: seriesGate(caps.tenant_series_writes, caps.series_writes),
@@ -665,7 +681,7 @@ export function createSlotlockRequestLimits(options) {
             const limited = {
                 async fetch(request, connection) {
                     const route = routeOf(request);
-                    const address = clientOf(request, connection, options.trustedProxyHeader);
+                    const address = clientOf(request, connection, options.trustedProxyHeader, proxySecretDigest);
                     addresses.set(request, address);
                     if (options.trustedProxyHeader === undefined && !fieldIgnored) {
                         const field = PROXY_CLIENT_FIELDS.find((name) => request.headers.has(name));

package/rest-api.d.ts

@@ -6,9 +6,8 @@ export interface SlotlockRestRoute<Operation extends string = SlotlockAgentOpera
     path: string;
     operation: Operation;
     /**
-     * The store refusals the route can answer besides the ones every route can: 404 for a record
-     * that is missing or another tenant's, 409 for a conflict with what is stored (an overlap, a
-     * stale revision). The OpenAPI document declares them, so a generated client types them.
+     * Store refusals the route can answer beyond the common ones: 404 (missing or another tenant's)
+     * and 409 (a conflict with what is stored). Declared in OpenAPI so generated clients type them.
      */
     refusals?: readonly (404 | 409)[];
 }
@@ -20,15 +19,15 @@ export declare const SLOTLOCK_PROBLEM_DOCS = "https://slotlock.pylota.io/docs/ap
 /** A problem type's identifier: a tag URI (RFC 4151), stable, one per code, not a locator. */
 export declare function slotlockProblemType(code: string): string;
 /**
- * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
- * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
- * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ * A REST refusal as RFC 9457 problem details: `type` and `title` name the problem, `code` is
+ * Slotlock's code, and `error.code` repeats it for older clients. `extensions` add context, such as
+ * the interval an overlap refused.
  */
 export declare function slotlockProblem(status: number, code: string, extensions?: Record<string, unknown>): Record<string, unknown>;
 /**
- * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
- * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
- * `null` when it is a quoted string that does not parse.
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, per
+ * draft-ietf-httpapi-idempotency-key-header-08), or a bare token as older clients send. `null` for
+ * a quoted string that does not parse.
  */
 export declare function parseIdempotencyKeyHeader(value: string): string | null;
 /** Where an operation's arguments come from. */
@@ -44,15 +43,15 @@ export type SlotlockRestMatch<Operation extends string = SlotlockAgentOperation>
     invalid: true;
 } | null;
 /**
- * The route for a method and path, the methods the path does have, or nothing. The first route in
- * `routes` that fits wins; no two of Slotlock's routes fit the same path and method (a test checks).
+ * The route for a method and path, the methods the path does have, or nothing. First fit wins; a
+ * test checks no two routes fit the same path and method.
  */
 export declare function matchSlotlockRestRoute<Operation extends string = SlotlockAgentOperation>(method: string, path: string, routes?: readonly SlotlockRestRoute<Operation>[]): SlotlockRestMatch<Operation>;
 type JsonSchema = Record<string, unknown>;
 /**
- * An operation's input from a query string: an array parameter repeats (`resource_ids=a&resource_ids=b`,
- * OpenAPI's default form style), every other parameter appears once. A parameter the operation does
- * not have, or a repeated one, is passed on as it is, so the operation's strict schema refuses it.
+ * An operation's input from a query string: array parameters repeat (OpenAPI's default form style),
+ * others appear once. Unknown or repeated parameters pass through so the strict schema refuses
+ * them.
  */
 export declare function restQueryInput(search: URLSearchParams, inputSchema: JsonSchema): Record<string, unknown>;
 /** One operation, as the OpenAPI document needs it. */

package/rest-api.js

@@ -86,9 +86,9 @@ const STATUS_TITLES = Object.freeze({
     503: 'Service Unavailable',
 });
 /**
- * A REST refusal as RFC 9457 problem details (`application/problem+json`): `type` and `title` name
- * the problem, `code` is Slotlock's code, and `error.code` repeats it, the body every earlier
- * client reads. `extensions` add what the refusal is about, such as the interval an overlap refused.
+ * A REST refusal as RFC 9457 problem details: `type` and `title` name the problem, `code` is
+ * Slotlock's code, and `error.code` repeats it for older clients. `extensions` add context, such as
+ * the interval an overlap refused.
  */
 export function slotlockProblem(status, code, extensions = {}) {
     return {
@@ -101,9 +101,9 @@ export function slotlockProblem(status, code, extensions = {}) {
     };
 }
 /**
- * The Idempotency-Key header's value: a Structured Field String (RFC 9651, as
- * draft-ietf-httpapi-idempotency-key-header-08 defines it), or the bare token clients sent before.
- * `null` when it is a quoted string that does not parse.
+ * The Idempotency-Key header's value: a Structured Field String (RFC 9651, per
+ * draft-ietf-httpapi-idempotency-key-header-08), or a bare token as older clients send. `null` for
+ * a quoted string that does not parse.
  */
 export function parseIdempotencyKeyHeader(value) {
     const trimmed = value.trim();
@@ -158,8 +158,8 @@ function matchPath(pattern, segments) {
     return params;
 }
 /**
- * The route for a method and path, the methods the path does have, or nothing. The first route in
- * `routes` that fits wins; no two of Slotlock's routes fit the same path and method (a test checks).
+ * The route for a method and path, the methods the path does have, or nothing. First fit wins; a
+ * test checks no two routes fit the same path and method.
  */
 export function matchSlotlockRestRoute(method, path, routes = SLOTLOCK_REST_ROUTES) {
     const segments = path.split('/');
@@ -209,9 +209,9 @@ function queryValue(value, schema) {
     return value;
 }
 /**
- * An operation's input from a query string: an array parameter repeats (`resource_ids=a&resource_ids=b`,
- * OpenAPI's default form style), every other parameter appears once. A parameter the operation does
- * not have, or a repeated one, is passed on as it is, so the operation's strict schema refuses it.
+ * An operation's input from a query string: array parameters repeat (OpenAPI's default form style),
+ * others appear once. Unknown or repeated parameters pass through so the strict schema refuses
+ * them.
  */
 export function restQueryInput(search, inputSchema) {
     const input = {};
@@ -338,7 +338,6 @@ export function slotlockOpenApiDocument(args) {
                 '403': ERROR_RESPONSE,
                 '404': ERROR_RESPONSE,
                 ...(route.method === 'GET' ? {} : { '409': ERROR_RESPONSE }),
-                // A change cursor past the feed's retention.
                 ...(route.operation === 'slotlock_list_changes' ? { '410': ERROR_RESPONSE } : {}),
                 '429': ERROR_RESPONSE,
                 default: ERROR_RESPONSE,

package/rules.d.ts

@@ -13,15 +13,14 @@ export declare function invalidWindowError(message?: string): Error & {
     code: 'invalid_window';
 };
 /**
- * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS. Expansion
- * is synchronous: fifty daily rules over a century are close to two million windows.
+ * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS: expansion
+ * is synchronous and grows with the window.
  */
 export declare function assertBoundedSearchWindow(window: Interval): void;
 /**
- * Expand availability rules to concrete, merged, sorted UTC windows clipped to `searchWindow`.
- * Unsupported or unparseable rules contribute nothing rather than throwing: one bad rule must not
- * blank the whole calendar — and must never manufacture availability the rule doesn't mean.
- * Callers should validate rules at write time; this read-path skip remains the fail-closed backstop.
- * A search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
+ * Expand availability rules to merged, sorted UTC windows clipped to `searchWindow`. Unsupported or
+ * unparseable rules contribute nothing rather than throwing: one bad rule must neither blank the
+ * calendar nor manufacture availability. Validate at write time; this is the fail-closed backstop.
+ * A window over SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
  */
 export declare function expandRules(rules: WeeklyAvailabilityRule[], searchWindow: Interval, timezone?: string): Interval[];

package/rules.js

@@ -21,15 +21,14 @@ export function invalidWindowError(message = 'Slotlock window must contain two f
     return Object.assign(new Error(message), { code: 'invalid_window' });
 }
 /**
- * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS. Expansion
- * is synchronous: fifty daily rules over a century are close to two million windows.
+ * Refuse (`invalid_window`) a search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS: expansion
+ * is synchronous and grows with the window.
  */
 export function assertBoundedSearchWindow(window) {
     if (window.end.getTime() - window.start.getTime() > MAX_SEARCH_WINDOW_MS) {
         throw invalidWindowError(`Slotlock searches a window of at most ${SLOTLOCK_CALENDAR_HORIZON_DAYS} days at once`);
     }
 }
-/** UTC midnight of the day containing `d`. */
 function utcDayFloor(d) {
     return new Date(Math.floor(d.getTime() / DAY_MS) * DAY_MS);
 }
@@ -38,15 +37,15 @@ const WEEKDAY = /^(?:MO|TU|WE|TH|FR|SA|SU)$/;
 const ABSOLUTE_UNTIL = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
 /**
  * Whether `until` is an absolute UNTIL naming a real instant. rrule reads it with Date.UTC, which
- * carries an overflowing field into the next unit: 31 February became 3 March, and the rule stayed
- * bookable after the day it was written to end. A leap second (60) is real (RFC 5545 3.3.12).
+ * carries overflow into the next unit (31 February becomes 3 March). A leap second (60) is real
+ * (RFC 5545 3.3.12).
  */
 function isRealUntil(until) {
     const match = ABSOLUTE_UNTIL.exec(until);
     if (!match)
         return false;
     const [, year, month, day, hour, minute, second] = match;
-    // Set without overflow checks, the date reads back differently when any part overflowed.
+    // Set without overflow checks: the date reads back differently when any part overflowed.
     const date = new Date(0);
     date.setUTCFullYear(Number(year), Number(month) - 1, Number(day));
     return (date.toISOString().startsWith(`${year}-${month}-${day}T`) &&
@@ -55,10 +54,10 @@ function isRealUntil(until) {
         Number(second) <= 60);
 }
 /**
- * Whether `rrule` is written in SPEC.md's subset: `FREQ=WEEKLY`, a `BYDAY` of plain weekdays,
- * optionally `INTERVAL=1` and an absolute `UNTIL`, each once, in any order, and nothing else.
- * Checked before rrule parses it: rrule honours a DTSTART's TZID (Monday came out as Sunday) and
- * the first BYDAY of two, and BYHOUR/BYMINUTE/BYSECOND multiply occurrences (one rule took 0.7 s).
+ * Whether `rrule` is in SPEC.md's subset: `FREQ=WEEKLY`, a `BYDAY` of plain weekdays, optionally
+ * `INTERVAL=1` and an absolute `UNTIL`, each once, in any order. Checked before rrule parses it:
+ * rrule honours a DTSTART's TZID, takes the first of two BYDAYs, and lets BYHOUR/BYMINUTE/BYSECOND
+ * multiply occurrences.
  */
 function isWeeklySubset(rrule) {
     const parts = new Map();
@@ -76,14 +75,12 @@ function isWeeklySubset(rrule) {
         (until === undefined || isRealUntil(until)));
 }
 /**
- * The spike honours exactly the weekly-cadence subset it can answer DETERMINISTICALLY. Anything
- * else is refused (skipped = fails closed to "not bookable"), never guessed:
- * - freq must be WEEKLY — a freq-less-but-parseable string ('', 'COUNT=5') otherwise becomes a
- *   default-YEARLY rule anchored at the query date: phantom availability at every search start.
- * - COUNT is unanswerable without an authored DTSTART — re-anchoring makes "first N occurrences"
- *   restart on every query.
- * - INTERVAL>1 parity depends on the anchor — re-anchoring makes biweekly availability flip with
- *   the query date. (UNTIL is absolute and expands correctly, so it stays allowed.)
+ * Only the weekly subset that can be answered deterministically; anything else fails closed to not
+ * bookable:
+ * - freq must be WEEKLY: a freq-less string otherwise becomes a YEARLY rule anchored at the query
+ *   date;
+ * - COUNT needs an authored DTSTART: re-anchoring restarts it on every query;
+ * - INTERVAL>1 parity depends on the anchor. UNTIL is absolute and stays allowed.
  */
 function isSupportedRule(parsed) {
     if (parsed.freq !== RRule.WEEKLY)
@@ -92,8 +89,8 @@ function isSupportedRule(parsed) {
         return false;
     if (parsed.interval !== undefined && parsed.interval !== 1)
         return false;
-    // BYDAY-less WEEKLY inherits its weekday from the re-anchored DTSTART — the answer wobbles
-    // with the query date (and, before this gate, flipped between the UTC and zoned paths).
+    // BYDAY-less WEEKLY would take its weekday from the re-anchored DTSTART, varying with the query
+    // date.
     const byweekday = parsed.byweekday;
     if (byweekday === undefined || byweekday === null)
         return false;
@@ -102,16 +99,14 @@ function isSupportedRule(parsed) {
     return true;
 }
 /**
- * Expand availability rules to concrete, merged, sorted UTC windows clipped to `searchWindow`.
- * Unsupported or unparseable rules contribute nothing rather than throwing: one bad rule must not
- * blank the whole calendar — and must never manufacture availability the rule doesn't mean.
- * Callers should validate rules at write time; this read-path skip remains the fail-closed backstop.
- * A search window longer than SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
+ * Expand availability rules to merged, sorted UTC windows clipped to `searchWindow`. Unsupported or
+ * unparseable rules contribute nothing rather than throwing: one bad rule must neither blank the
+ * calendar nor manufacture availability. Validate at write time; this is the fail-closed backstop.
+ * A window over SLOTLOCK_CALENDAR_HORIZON_DAYS is refused (`invalid_window`).
  */
 export function expandRules(rules, searchWindow, timezone) {
     assertBoundedSearchWindow(searchWindow);
-    // Validate ONCE, loudly: a typo'd zone must never silently fall back to UTC math — that
-    // would manufacture availability shifted by the zone offset. 'UTC'/omitted = spike path.
+    // Validate once: a typo'd zone must never silently fall back to UTC and shift availability.
     const converter = timezone !== undefined ? createTimeZoneConverter(timezone) : null;
     const windows = [];
     for (const rule of rules) {
@@ -125,9 +120,8 @@ export function expandRules(rules, searchWindow, timezone) {
         }
         let rrule;
         let absoluteUntil = null;
-        // A window can START days before the search window and still reach into it — scan the
-        // recurrence back far enough for the longest window this rule can produce (multi-day
-        // windows like "Mon 00:00 + 3 days" are legal; a fixed one-day margin silently lost them).
+        // A window can start days before the search window and still reach into it: scan back as far as
+        // the longest window this rule can produce.
         const backScanDays = Math.ceil((rule.startMinutes + rule.durationMinutes) / (24 * 60));
         const scanStart = utcDayFloor(new Date(searchWindow.start.getTime() - backScanDays * DAY_MS));
         if (typeof rule.rrule !== 'string' || !isWeeklySubset(rule.rrule))
@@ -136,10 +130,8 @@ export function expandRules(rules, searchWindow, timezone) {
             const parsed = RRule.parseString(rule.rrule);
             if (!isSupportedRule(parsed))
                 continue;
-            // rrule's stamps are days, not window starts: a UTC midnight, or under a zone a LOCAL date
-            // read as UTC. Left to rrule, UNTIL would keep a window that starts after it on its own day,
-            // and under a zone east of UTC drop one that starts before it. Each window's real start is
-            // compared with UNTIL instead (below), with or without a zone, so the two paths agree.
+            // rrule's stamps are days, not window starts, so its UNTIL handling is wrong at both ends;
+            // each window's real start is compared with UNTIL below instead.
             if (parsed.until) {
                 absoluteUntil = parsed.until;
                 parsed.until = null;
@@ -150,19 +142,16 @@ export function expandRules(rules, searchWindow, timezone) {
         catch {
             continue;
         }
-        // Under a zone, a LOCAL day whose UTC stamp lies past the window end can still start
-        // before it (east zones read a stamp's wall date up to 14h earlier) — scan one day over
-        // and let clipping discard the overshoot.
+        // Under a zone a local day whose UTC stamp is past the window end can still start before it
+        // (east zones are up to 14h ahead): scan one day over and let clipping discard the overshoot.
         const scanEnd = converter ? new Date(searchWindow.end.getTime() + DAY_MS) : searchWindow.end;
         const days = rrule.between(scanStart, scanEnd, true);
         for (const day of days) {
             let start;
             let end;
             if (converter) {
-                // The stamp's Y/M/D is the LOCAL calendar date; start and end are both wall-clock. An
-                // edge the clocks skip stands where the skipped hour ends: moved on by the gap, as RFC 5545
-                // reads a time, [02:30, 03:30) gave nothing although 03:00-03:30 exists, and [02:00,
-                // 02:30) gave 03:00-03:30, which it never names.
+                // The stamp's Y/M/D is the local date; start and end are wall-clock. An edge the clocks
+                // skip stands where the skipped hour ends, so the window holds only wall times that exist.
                 const wallDay = Date.UTC(day.getUTCFullYear(), day.getUTCMonth(), day.getUTCDate());
                 start = converter.wallFrameToUtc(wallDay + rule.startMinutes * MINUTE_MS, { gap: 'end' });
                 end = converter.wallFrameToUtc(wallDay + (rule.startMinutes + rule.durationMinutes) * MINUTE_MS, { gap: 'end' });
@@ -176,7 +165,6 @@ export function expandRules(rules, searchWindow, timezone) {
             }
             if (absoluteUntil && start.getTime() > absoluteUntil.getTime())
                 continue;
-            // Clip to the search window; drop windows that miss it entirely.
             const clippedStart = start.getTime() < searchWindow.start.getTime() ? searchWindow.start : start;
             const clippedEnd = end.getTime() > searchWindow.end.getTime() ? searchWindow.end : end;
             if (clippedStart.getTime() < clippedEnd.getTime()) {

package/self-host.d.ts

@@ -5,7 +5,7 @@ import { type SlotlockSql, type SlotlockStore } from './store.js';
 import type { WeeklyAvailabilityRule } from './types.js';
 export { SlotlockConfigError, type SlotlockEnv, type SlotlockServeDashboardConfig };
 /** Every variable the commands read. The README, `.env.example` and `server.json` document these. */
-export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "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_ASSISTANT_SECRET", "SLOTLOCK_ASSISTANT_PRIVATE_URLS", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "HOST", "PORT"];
+export declare const SLOTLOCK_ENVIRONMENT_VARIABLES: readonly ["DATABASE_URL", "SLOTLOCK_MIGRATE_DATABASE_URL", "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_TRUSTED_PROXY_SECRET", "SLOTLOCK_GITHUB_CLIENT_ID", "SLOTLOCK_GITHUB_CLIENT_SECRET", "SLOTLOCK_SESSION_SECRET", "SLOTLOCK_ASSISTANT_SECRET", "SLOTLOCK_ASSISTANT_PRIVATE_URLS", "SLOTLOCK_DASHBOARD_USERS", "SLOTLOCK_DASHBOARD_ORGS", "SLOTLOCK_DASHBOARD_NAME", "HOST", "PORT"];
 export interface SlotlockDatabaseConfig {
     /** The role `serve` and `resource` connect as. */
     databaseUrl: string;
@@ -49,6 +49,11 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
      * keys may act for, whether it serves the dashboard or another server (a Worker) does.
      */
     organizations?: string[];
+    /**
+     * GitHub user ids (SLOTLOCK_DASHBOARD_USERS), or `'*'`, whose `github:<id>` tenants this server's
+     * keys may act for, whether it serves the dashboard or another server (a Worker) does.
+     */
+    allowedUsers?: '*' | string[];
     /**
      * Serve the REST API under /v1, with the application API for admin keys, and its OpenAPI document
      * (SLOTLOCK_REST_API: on unless off).
@@ -62,6 +67,8 @@ export interface SlotlockServeConfig extends SlotlockDatabaseConfig {
     limits: SlotlockLimits;
     /** The lower-case request field a trusted proxy sets to the client address; else the socket's. */
     trustedProxyHeader?: string;
+    /** The value that must accompany trustedProxyHeader in x-slotlock-proxy-proof; else the socket's. */
+    trustedProxySecret?: string;
 }
 export declare function readSlotlockDatabaseConfig(env: SlotlockEnv): SlotlockDatabaseConfig;
 export declare function readSlotlockServeConfig(env: SlotlockEnv): SlotlockServeConfig;
@@ -110,6 +117,13 @@ export interface SlotlockRunningServer {
     /** End open subscriptions, drain in-flight requests, then close the database pool. */
     close(): Promise<SlotlockNodeServerCloseResult>;
 }
+/**
+ * Whether the dashboard's allowlists let a tenant act, wherever the dashboard runs: a
+ * `github-org:<id>` tenant only while SLOTLOCK_DASHBOARD_ORGS lists that organization; a
+ * `github:<id>` tenant only while SLOTLOCK_DASHBOARD_USERS is `*` or lists that id; every tenant when
+ * SLOTLOCK_DASHBOARD_USERS is not set, and every other tenant.
+ */
+export declare function slotlockServeAllowsTenant(config: Pick<SlotlockServeConfig, 'organizations' | 'allowedUsers'>, tenantRef: string): boolean;
 /**
  * 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.
@@ -124,7 +138,7 @@ export declare function createSlotlockMaintenanceStore(sql: SlotlockSql, caps: S
 }): SlotlockStore;
 /** Serve MCP and A2A over HTTP from the Postgres store, as one token-authenticated tenant. */
 export declare function startSlotlockServer(config: SlotlockServeConfig, log: SlotlockLogger): Promise<SlotlockRunningServer>;
-export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains each tenant it serves every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  rules set <json> --resource <ref>\n                           Set what a booking on the resource must satisfy, like\n                           {\"minNoticeMinutes\":120,\"slotStepMinutes\":30,\"turnaroundMinutes\":30,\"enforceHours\":true}\n  rules clear --resource <ref>\n                           Remove the resource's booking rules\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+\n                                 random characters (serve; off without it)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,\n                                 and retired answers (never under 30) (1-3650, default 30;\n                                 serve and maintain)\n  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the\n                                 database, so N servers allow a tenant its rate once; off (default):\n                                 each server keeps its own\n  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,\n                                 never to a private network address; private: those too, for\n                                 testing; off: keep the change feed, send nothing\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000), holder_holds (20) and\n                                 holder_held_hours (2160), which maintain keeps too\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's\n                                 model API key with it, 32+ random characters (dashboard; off\n                                 without it)\n  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or\n                                 resolves to, a loopback, private, link-local, CGNAT, unique-local\n                                 or metadata address; on: allow them, for a self-hosted model\n                                 (Ollama, vLLM) on this machine or network\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in (dashboard)\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
+export declare const SLOTLOCK_CLI_HELP = "Usage: slotlock <command> [options]\n\nCommands:\n  migrate                  Apply the schema and row-level security, then grant the serving\n                           role when SLOTLOCK_MIGRATE_DATABASE_URL names another role\n  serve [--migrate]        Serve MCP, A2A and REST over HTTP (--migrate runs migrate first);\n                           maintains every tenant with data every hour\n  maintain                 Run maintenance for the tenant now: extend recurring events to the\n                           rolling horizon and prune past the retention window (for cron)\n  resource add <ref> [--timezone <IANA zone>]\n                           Create a calendar resource (a car, room, person or machine)\n  resource list            Print the tenant's resources, one JSON object per line\n  resource archive <ref>   Take a resource out of use: no new bookings, holds or events, and\n                           no longer listed; what is on it stays\n  resource restore <ref>   Put an archived resource back in use\n  resource delete <ref>    Delete a resource and its history; refused while a booking, hold\n                           or event on it has not ended\n  hours show [--resource <ref>]\n                           Print each resource's bookable hours (null: the server's)\n  hours set <json> (--resource <ref> | --all)\n                           Give one resource, or every one, weekly hours of its own; [] closes\n  hours clear (--resource <ref> | --all)\n                           Hand one resource, or every one, back to the server's hours\n  rules set <json> --resource <ref>\n                           Set what a booking on the resource must satisfy, like\n                           {\"minNoticeMinutes\":120,\"slotStepMinutes\":30,\"turnaroundMinutes\":30,\"enforceHours\":true}\n  rules clear --resource <ref>\n                           Remove the resource's booking rules\n  key create <name> [--scope read,write,admin] [--expires-in-days <n>]\n                           Create an API key for the tenant (default scope read,write, no\n                           expiry; admin adds the application API) and print it once; only its\n                           SHA-256 is stored\n  key list                 Print the tenant's API keys, one JSON object per line\n  key rotate <id>          Give an active key a new secret and print it once; the old one stops\n                           working at once, and the key keeps its id and what it booked\n  key revoke <id>          Revoke one of the tenant's API keys at once\n  tenant status            Print whether the tenant is suspended\n  tenant suspend [--reason <text>]\n                           Suspend the tenant: it may read, and writes nothing; its keys get\n                           no new secret (as SLOTLOCK_MIGRATE_DATABASE_URL's role when set:\n                           only the schema owner suspends)\n  tenant unsuspend         Lift the tenant's suspension (as the schema owner, likewise)\n  tenant erase --confirm <tenant>\n                           Delete everything the tenant has, its API keys included, for good;\n                           --confirm repeats SLOTLOCK_TENANT\n  healthcheck              Exit 0 when the local server reports ready\n\nOptions:\n  -h, --help               Show this help\n  -v, --version            Print the version\n\nEnvironment:\n  DATABASE_URL                   postgres:// URL of the role Slotlock serves as (required); serve\n                                 refuses a superuser or a role with BYPASSRLS\n  SLOTLOCK_MIGRATE_DATABASE_URL  postgres:// URL of the schema owner, for migrate (optional)\n  SLOTLOCK_AUTH_TOKEN            Optional bearer token for SLOTLOCK_TENANT with read and write\n                                 access (never admin), 32+ random characters (serve); API keys\n                                 work with or without it\n  SLOTLOCK_CONFIRMATION_SECRET   Signs pending write confirmations, 32+ random characters (serve;\n                                 required when SLOTLOCK_CONFIRM_WRITES is not none)\n  SLOTLOCK_METRICS_TOKEN         Serves Prometheus metrics at /metrics to this bearer token, 32+\n                                 random characters (serve; off without it)\n  SLOTLOCK_CONFIRM_WRITES        none (default), all, or a comma-separated list of write tools\n                                 that wait for a person (MCP 2026-07-28 form elicitation; refused\n                                 with confirmation_required on REST, A2A and older MCP)\n  SLOTLOCK_PUBLIC_URL            URL clients use (default http://localhost:$PORT)\n  SLOTLOCK_TENANT                Tenant of the token, resource and key commands (default \"default\")\n  SLOTLOCK_AVAILABILITY          JSON array of weekly bookable-hours rules (default: none)\n  SLOTLOCK_REST_API              on (default): also serve the tools as a REST API under /v1, and\n                                 the application API for admin keys, described at /openapi.json;\n                                 off: MCP and A2A only\n  SLOTLOCK_RETENTION_DAYS        Days of history kept: the change feed, ended waitlist entries,\n                                 and retired answers (never under 30) (1-3650, default 30;\n                                 serve and maintain)\n  SLOTLOCK_SHARED_LIMITS         on: tenant request budgets are shared by every server through the\n                                 database, so N servers allow a tenant its rate once; off (default):\n                                 each server keeps its own\n  SLOTLOCK_WEBHOOKS              on (default): deliver each tenant's changes to its webhooks,\n                                 never to a private network address; private: those too, for\n                                 testing; off: keep the change feed, send nothing\n  SLOTLOCK_LIMITS                Request limits, comma-separated name=value over the defaults:\n                                 rates as <count>/<s|m|h>[:<burst>] or off for address (50/s:100,\n                                 every request per client, before any key lookup), key_read,\n                                 tenant_read (20/s:40), key_write, tenant_write (5/s:20),\n                                 global_read (500/s:1000), global_write (50/s:100), app_read\n                                 (20/s:40) and app_write (5/s:20) per tenant for the\n                                 application API, sign_in (20/m:20); counts for\n                                 tenant_series_writes and series_writes\n                                 (1: writes that may expand a recurring series at once),\n                                 maintenance_runs (1: application API maintenance runs at once),\n                                 subscriptions (256), tenant_subscriptions (16),\n                                 key_subscriptions (4, and fewer than tenant_subscriptions),\n                                 key_lookups (2), key_lookup_queue (256),\n                                 tenant_transactions (2: one tenant's database transactions at\n                                 once, of the pool's 10); what one tenant may store:\n                                 tenant_holds (10000), tenant_reservations, tenant_events and\n                                 tenant_coverage (100000), holder_holds (20) and\n                                 holder_held_hours (2160), which maintain keeps too\n  SLOTLOCK_TRUSTED_PROXY_HEADER  The request field a proxy in front sets to the client address,\n                                 such as CF-Connecting-IP (default: the connection's address);\n                                 set it only when every request comes through that proxy\n  SLOTLOCK_TRUSTED_PROXY_SECRET  A secret the proxy adds to every request in x-slotlock-proxy-proof,\n                                 32+ random characters: without it there, the field above is\n                                 ignored and the connection's address counts\n  SLOTLOCK_GITHUB_CLIENT_ID      Serve the dashboard at $SLOTLOCK_PUBLIC_URL/dashboard: the Client ID\n                                 of a GitHub OAuth app with callback .../dashboard/callback\n  SLOTLOCK_GITHUB_CLIENT_SECRET  That app's client secret (dashboard)\n  SLOTLOCK_SESSION_SECRET        Signs dashboard sessions, 32+ random characters (dashboard)\n  SLOTLOCK_ASSISTANT_SECRET      Turns on the dashboard assistant and seals each organization's\n                                 model API key with it, 32+ random characters (dashboard; off\n                                 without it)\n  SLOTLOCK_ASSISTANT_PRIVATE_URLS off (default): refuse an assistant model URL whose host is, or\n                                 resolves to, a loopback, private, link-local, CGNAT, unique-local\n                                 or metadata address; on: allow them, for a self-hosted model\n                                 (Ollama, vLLM) on this machine or network\n  SLOTLOCK_DASHBOARD_USERS       * or comma-separated GitHub user ids that may sign in and whose keys work\n  SLOTLOCK_DASHBOARD_ORGS        comma-separated GitHub organization ids: each is one shared tenant\n  SLOTLOCK_DASHBOARD_NAME        What the dashboard calls this deployment (default Slotlock)\n  HOST                           Listen address (default 127.0.0.1)\n  PORT                           Listen port (default 8080)\n\nGenerate each secret with: openssl rand -hex 32\n";
 /**
  * Run one `slotlock` command and resolve to its exit code: 0 success, 1 failure, 2 a usage or
  * configuration error (nothing was started). `serve` resolves once `io.signal` aborts and it has