slotlock 0.1.1 → 0.3.0

package/api-keys.d.ts

@@ -1,10 +1,17 @@
-import { type SlotlockAgentPrincipal, type SlotlockAgentScope } from './agent-server.js';
+import { type SlotlockAgentPrincipal } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
 import type { SlotlockSql } from './store.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
-/** `read` covers the operations that only look; `write` the ones that change a calendar. */
-export declare const SLOTLOCK_API_KEY_SCOPES: readonly ["read", "write"];
-export type SlotlockApiKeyScope = SlotlockAgentScope;
+/**
+ * `read` covers the agent operations that only look; `write` the ones that change a calendar; `admin`
+ * the application API (application-api.ts: resources, bookable hours, holds, reservations, coverage
+ * and maintenance), for an application's backend rather than an agent. A key's scopes are stored in
+ * this order.
+ */
+export declare const SLOTLOCK_API_KEY_SCOPES: readonly ["read", "write", "admin"];
+/** What a key gets unless it asks for more: what an agent needs. `admin` is never a default. */
+export declare const SLOTLOCK_API_KEY_DEFAULT_SCOPES: readonly ["read", "write"];
+export type SlotlockApiKeyScope = (typeof SLOTLOCK_API_KEY_SCOPES)[number];
 /** Every key starts with this, so a person or a secret scanner can tell what it is. */
 export declare const SLOTLOCK_API_KEY_PREFIX = "slk_";
 /** The longest a key may live: ten years. A key without an expiry lives until it is revoked. */
@@ -110,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;
 }
 /**
@@ -119,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,10 +8,18 @@
 // 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 };
-/** `read` covers the operations that only look; `write` the ones that change a calendar. */
-export const SLOTLOCK_API_KEY_SCOPES = Object.freeze(['read', 'write']);
+/**
+ * `read` covers the agent operations that only look; `write` the ones that change a calendar; `admin`
+ * the application API (application-api.ts: resources, bookable hours, holds, reservations, coverage
+ * and maintenance), for an application's backend rather than an agent. A key's scopes are stored in
+ * this order.
+ */
+export const SLOTLOCK_API_KEY_SCOPES = Object.freeze(['read', 'write', 'admin']);
+/** What a key gets unless it asks for more: what an agent needs. `admin` is never a default. */
+export const SLOTLOCK_API_KEY_DEFAULT_SCOPES = Object.freeze(['read', 'write']);
 /** Every key starts with this, so a person or a secret scanner can tell what it is. */
 export const SLOTLOCK_API_KEY_PREFIX = 'slk_';
 /** The longest a key may live: ten years. A key without an expiry lives until it is revoked. */
@@ -34,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 });
 }
@@ -223,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;
@@ -243,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,
@@ -270,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

@@ -0,0 +1,67 @@
+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_archive_resource' | 'slotlock_restore_resource' | 'slotlock_delete_resource' | 'slotlock_list_busy' | 'slotlock_set_resource_availability' | 'slotlock_set_tenant_availability' | '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_record_coverage' | 'slotlock_list_tenant_events' | 'slotlock_get_tenant_event' | 'slotlock_cancel_tenant_event' | 'slotlock_get_tenant' | 'slotlock_erase_tenant' | 'slotlock_run_maintenance';
+/** The scope an application operation needs, whichever operation it is. */
+export declare const SLOTLOCK_APPLICATION_SCOPE = "admin";
+export interface SlotlockApplicationInvocationContext {
+    principal: SlotlockAgentPrincipal;
+    operation: SlotlockApplicationOperation;
+    signal: AbortSignal;
+    /** W3C trace context the caller sent, already validated. */
+    trace?: SlotlockTraceContext;
+}
+type Handler = (context: SlotlockApplicationInvocationContext, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/**
+ * What serves the application operations. Every method receives the input its operation's schema
+ * accepted, and returns what its output schema describes; a refusal is a thrown
+ * `SlotlockAgentOperationError`. The tenant is the principal's, never an argument.
+ */
+export interface SlotlockApplicationBackend {
+    createResource: Handler;
+    getResource: Handler;
+    archiveResource: Handler;
+    restoreResource: Handler;
+    deleteResource: Handler;
+    listBusy: Handler;
+    setResourceAvailability: Handler;
+    setTenantAvailability: Handler;
+    acquireHold: Handler;
+    getHold: Handler;
+    listHolds: Handler;
+    confirmHold: Handler;
+    releaseHold: Handler;
+    getReservation: Handler;
+    listReservations: Handler;
+    putReservation: Handler;
+    cancelReservation: Handler;
+    recordCoverage: Handler;
+    listTenantEvents: Handler;
+    getTenantEvent: Handler;
+    cancelTenantEvent: Handler;
+    getTenant: Handler;
+    eraseTenant: Handler;
+    runMaintenance: Handler;
+}
+export interface SlotlockApplicationOperationDefinition {
+    name: SlotlockApplicationOperation;
+    title: string;
+    description: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    /** Relative to the server's base URL; `{name}` is one path segment, an input of that name. */
+    path: string;
+    input: z.ZodType<Record<string, unknown>>;
+    output: z.ZodType<Record<string, unknown>>;
+    risk: {
+        readOnly: boolean;
+        destructive: boolean;
+        idempotent: boolean;
+    };
+    invoke: keyof SlotlockApplicationBackend;
+    /** Valid input, path parameters included (a test runs each against the schema). */
+    example: Record<string, unknown>;
+}
+export declare const SLOTLOCK_APPLICATION_OPERATIONS: readonly SlotlockApplicationOperationDefinition[];
+export declare function isSlotlockApplicationOperation(name: unknown): name is SlotlockApplicationOperation;
+export declare function slotlockApplicationOperation(name: SlotlockApplicationOperation): SlotlockApplicationOperationDefinition;
+export {};