slotlock 0.2.0 → 0.5.0

package/api-keys.d.ts

@@ -117,7 +117,10 @@ export declare function createSlotlockApiKeyStore(sql: SlotlockSql): SlotlockApi
 export interface SlotlockApiKeyAuthenticatorOptions {
     /** Key lookups that may run at once, default 2: at most this many connections serve them. */
     maxConcurrentLookups?: number;
-    /** Lookups that may wait for one, default 256. A request beyond that is anonymous at once. */
+    /**
+     * Lookups that may wait for one, default 256, and as many again for keys that recently
+     * authenticated. A request beyond that is refused as busy at once.
+     */
     maxWaitingLookups?: number;
 }
 /**
@@ -126,7 +129,12 @@ export interface SlotlockApiKeyAuthenticatorOptions {
  * `authorize`. A value that is not a well-formed key is anonymous without a lookup.
  *
  * Anyone can make well-formed keys, so lookups are bounded: a flood of made-up keys waits for at
- * most `maxConcurrentLookups` connections and is refused past `maxWaitingLookups`, and the rest of
- * the pool stays free for authenticated work. Rate-limit a public server in front of it as well.
+ * most `maxConcurrentLookups` connections, and past `maxWaitingLookups` a request is refused with a
+ * `SlotlockAgentOperationError` (`server_busy`, 503) rather than answered anonymous, which would
+ * tell a client holding a valid key that its key is bad. A key that authenticated in the last 15
+ * minutes waits in a queue of its own that is served first, so made-up keys, which never
+ * authenticate, cannot keep it waiting. Every request is still looked up, so a revoked key stops
+ * at once. Rate-limit a public server in front of it as well (`slotlock serve` does, per client
+ * address, before any lookup).
  */
 export declare function createSlotlockApiKeyAuthenticator(keys: Pick<SlotlockApiKeyStore, 'authenticate'>, options?: SlotlockApiKeyAuthenticatorOptions): (request: Request) => Promise<SlotlockAgentPrincipal | null>;

package/api-keys.js

@@ -8,6 +8,7 @@
 // cannot reach another tenant's keys, read a digest, or bring back a revoked, rotated-out or erased
 // key.
 import { createHash, randomBytes } from 'node:crypto';
+import { SlotlockAgentOperationError, } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
@@ -41,6 +42,10 @@ const DAY_MS = 86_400_000;
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const DEFAULT_MAX_CONCURRENT_LOOKUPS = 2;
 const DEFAULT_MAX_WAITING_LOOKUPS = 256;
+/** How long a key that authenticated keeps its place ahead of unknown keys in the lookup queue. */
+const RECENTLY_VALID_MS = 15 * 60_000;
+/** Keys the authenticator remembers as recently valid, by digest; past this the oldest go first. */
+const MAX_RECENTLY_VALID = 10_000;
 function invalid(code, message) {
     return Object.assign(new Error(message), { code });
 }
@@ -230,14 +235,21 @@ export function createSlotlockApiKeyStore(sql) {
         },
     };
 }
+/** What the authenticator throws when its lookup queue is full: retry later, the key may be fine. */
+const LOOKUP_BUSY = 'server_busy';
 /**
  * Bearer authentication by API key: a request carrying an active key is that key's principal,
  * `api_key:<id>` in the key's own tenant with its scopes, which the agent server enforces before
  * `authorize`. A value that is not a well-formed key is anonymous without a lookup.
  *
  * Anyone can make well-formed keys, so lookups are bounded: a flood of made-up keys waits for at
- * most `maxConcurrentLookups` connections and is refused past `maxWaitingLookups`, and the rest of
- * the pool stays free for authenticated work. Rate-limit a public server in front of it as well.
+ * most `maxConcurrentLookups` connections, and past `maxWaitingLookups` a request is refused with a
+ * `SlotlockAgentOperationError` (`server_busy`, 503) rather than answered anonymous, which would
+ * tell a client holding a valid key that its key is bad. A key that authenticated in the last 15
+ * minutes waits in a queue of its own that is served first, so made-up keys, which never
+ * authenticate, cannot keep it waiting. Every request is still looked up, so a revoked key stops
+ * at once. Rate-limit a public server in front of it as well (`slotlock serve` does, per client
+ * address, before any lookup).
  */
 export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
     const maxActive = options.maxConcurrentLookups ?? DEFAULT_MAX_CONCURRENT_LOOKUPS;
@@ -250,26 +262,37 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
     }
     let active = 0;
     const waiting = [];
+    const waitingKnown = [];
+    /** Digests of keys that recently authenticated, oldest first, with when they stop counting. */
+    const recentlyValid = new Map();
     return async (request) => {
         const presented = slotlockBearerCredential(request);
         if (presented === undefined || !isSlotlockApiKey(presented))
             return null;
+        const digest = slotlockApiKeyDigest(presented).toString('hex');
+        const known = (recentlyValid.get(digest) ?? 0) > Date.now();
+        const queue = known ? waitingKnown : waiting;
         if (active < maxActive) {
             active += 1;
         }
-        else if (waiting.length < maxWaiting) {
+        else if (queue.length < maxWaiting) {
             // A finishing lookup hands its slot straight to the next waiter, so `active` is unchanged.
-            await new Promise((resolve) => waiting.push(resolve));
+            await new Promise((resolve) => queue.push(resolve));
         }
         else {
-            return null;
+            throw new SlotlockAgentOperationError(LOOKUP_BUSY, 503);
         }
         try {
             if (request.signal.aborted)
                 return null;
             const identity = await keys.authenticate(presented);
+            recentlyValid.delete(digest);
             if (!identity)
                 return null;
+            recentlyValid.set(digest, Date.now() + RECENTLY_VALID_MS);
+            if (recentlyValid.size > MAX_RECENTLY_VALID) {
+                recentlyValid.delete(recentlyValid.keys().next().value);
+            }
             return {
                 subject: `api_key:${identity.id}`,
                 tenantRef: identity.tenantRef,
@@ -277,7 +300,7 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
             };
         }
         finally {
-            const next = waiting.shift();
+            const next = waitingKnown.shift() ?? waiting.shift();
             if (next)
                 next();
             else

package/application-api.d.ts

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import type { SlotlockAgentPrincipal } from './agent-server.js';
 import type { SlotlockTraceContext } from './mcp-modern.js';
-export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_acquire_hold' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_record_coverage' | 'slotlock_run_maintenance';
+export type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_get_resource' | 'slotlock_archive_resource' | 'slotlock_restore_resource' | 'slotlock_delete_resource' | 'slotlock_list_busy' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | 'slotlock_export_resource_availability' | 'slotlock_import_resource_availability' | 'slotlock_set_resource_booking_rules' | 'slotlock_set_resource_pool' | 'slotlock_list_pools' | 'slotlock_get_resource_history' | 'slotlock_get_coverage' | 'slotlock_record_coverage_failure' | 'slotlock_delete_coverage' | 'slotlock_get_reservation_history' | 'slotlock_get_tenant_event_history' | 'slotlock_acquire_hold' | 'slotlock_get_hold' | 'slotlock_list_holds' | 'slotlock_confirm_hold' | 'slotlock_release_hold' | 'slotlock_get_reservation' | 'slotlock_list_reservations' | 'slotlock_put_reservation' | 'slotlock_cancel_reservation' | 'slotlock_check_in_reservation' | 'slotlock_join_waitlist' | 'slotlock_list_waitlist' | 'slotlock_leave_waitlist' | 'slotlock_record_coverage' | 'slotlock_list_tenant_events' | 'slotlock_get_tenant_event' | 'slotlock_export_tenant_event' | 'slotlock_cancel_tenant_event' | 'slotlock_get_tenant' | 'slotlock_erase_tenant' | 'slotlock_run_maintenance' | 'slotlock_list_changes' | 'slotlock_create_webhook' | 'slotlock_list_webhooks' | 'slotlock_delete_webhook' | 'slotlock_enable_webhook';
 /** The scope an application operation needs, whichever operation it is. */
 export declare const SLOTLOCK_APPLICATION_SCOPE = "admin";
 export interface SlotlockApplicationInvocationContext {
@@ -20,15 +20,49 @@ type Handler = (context: SlotlockApplicationInvocationContext, input: Record<str
 export interface SlotlockApplicationBackend {
     createResource: Handler;
     getResource: Handler;
+    archiveResource: Handler;
+    restoreResource: Handler;
+    deleteResource: Handler;
+    listBusy: Handler;
     setResourceAvailability: Handler;
     setTenantAvailability: Handler;
+    exportResourceAvailability: Handler;
+    importResourceAvailability: Handler;
+    setResourceBookingRules: Handler;
+    setResourcePool: Handler;
+    listPools: Handler;
+    getResourceHistory: Handler;
+    getCoverage: Handler;
+    recordCoverageFailure: Handler;
+    deleteCoverage: Handler;
+    getReservationHistory: Handler;
+    getTenantEventHistory: Handler;
     acquireHold: Handler;
+    getHold: Handler;
+    listHolds: Handler;
     confirmHold: Handler;
     releaseHold: Handler;
+    getReservation: Handler;
+    listReservations: Handler;
     putReservation: Handler;
     cancelReservation: Handler;
+    checkInReservation: Handler;
+    joinWaitlist: Handler;
+    listWaitlist: Handler;
+    leaveWaitlist: Handler;
     recordCoverage: Handler;
+    listTenantEvents: Handler;
+    getTenantEvent: Handler;
+    exportTenantEvent: Handler;
+    cancelTenantEvent: Handler;
+    getTenant: Handler;
+    eraseTenant: Handler;
     runMaintenance: Handler;
+    listChanges: Handler;
+    createWebhook: Handler;
+    listWebhooks: Handler;
+    deleteWebhook: Handler;
+    enableWebhook: Handler;
 }
 export interface SlotlockApplicationOperationDefinition {
     name: SlotlockApplicationOperation;