slotlock 0.6.3 → 0.8.0

package/api-keys.d.ts

@@ -1,6 +1,7 @@
 import { type SlotlockAgentPrincipal } from './agent-server.js';
 import { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT } from './ddl.js';
 import { type SlotlockChangeOrigin } from './event-feed.js';
+import { type SlotlockResourceScope } from './resource-profile.js';
 import type { SlotlockSql } from './store.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
@@ -22,7 +23,7 @@ export interface SlotlockApiKey {
     id: string;
     tenantRef: string;
     name: string;
-    /** `slk_` and the next 8 characters of the key. */
+    /** `slk_` (`slk_test_` in a test environment) and the next 8 characters of the key. */
     prefix: string;
     scopes: SlotlockApiKeyScope[];
     /** Who created it, as the caller recorded it (`cli`, `github:<id>`), or null. */
@@ -32,12 +33,36 @@ export interface SlotlockApiKey {
     /** When the key last authenticated, to the minute. */
     lastUsedAt: Date | null;
     revokedAt: Date | null;
+    /** For a key limited to part of its tenant (RFC 0003 G6), the locations and groups it reaches. */
+    resourceScope?: SlotlockResourceScope;
+    /** What the key may do below the server's limits (RFC 0004 A5), when anything is set. */
+    limits?: SlotlockApiKeyLimits;
 }
+/**
+ * One agent's key held below the server's limits (RFC 0004 A5). Each only lowers: the server's own
+ * limit applies where it is lower, and on a hosted plan the plan's. Unset fields are the server's.
+ */
+export interface SlotlockApiKeyLimits {
+    /** Live holds at once (the server's `holder_holds`, 20 by default), 1-10,000. */
+    maxHolds?: number;
+    /** Hours its live holds may hold together (`holder_held_hours`, 2,160), 1-876,000. */
+    maxHeldHours?: number;
+    /** Requests a minute, reads and writes alike, on top of the server's per-key rates; 1-100,000. */
+    requestsPerMinute?: number;
+    /** Every booking it makes waits for a person (RFC 0004 A4), as an approval policy would hold it. */
+    requiresApproval?: boolean;
+}
+/** Whether `value` is a valid SlotlockApiKeyLimits. */
+export declare function isSlotlockApiKeyLimits(value: unknown): value is SlotlockApiKeyLimits;
 /** What an active key authenticates as. */
 export interface SlotlockApiKeyIdentity {
     id: string;
     tenantRef: string;
     scopes: SlotlockApiKeyScope[];
+    /** Set for a key limited to part of its tenant: withTenant holds it to these resources. */
+    resourceScope?: SlotlockResourceScope;
+    /** Set for a key with limits of its own (RFC 0004 A5). */
+    limits?: SlotlockApiKeyLimits;
 }
 export interface CreateSlotlockApiKeyInput {
     tenantRef: string;
@@ -51,6 +76,14 @@ export interface CreateSlotlockApiKeyInput {
     actor?: string;
     /** Where from, for the feed (`dashboard`, say); else the enclosing withTenant's, or `library`. */
     origin?: SlotlockChangeOrigin;
+    /**
+     * Limit the key to the resources at these locations (each with every location in it) or in these
+     * groups (RFC 0003 G6), for good: up to 20 of each. Read and write keys only: a limited key with
+     * `admin` is refused (`invalid_api_key_scopes`), since admin operations are the whole tenant's.
+     */
+    resourceScope?: SlotlockResourceScope;
+    /** Hold the key below the server's limits (RFC 0004 A5); `setLimits` changes them later. */
+    limits?: SlotlockApiKeyLimits;
 }
 /** Who rotates or revokes a key and from where, recorded on the feed as `create`'s are. */
 export interface SlotlockApiKeyChange {
@@ -93,6 +126,15 @@ export interface SlotlockApiKeyStore {
         tenantRef: string;
         id: string;
     } & SlotlockApiKeyChange): Promise<SlotlockApiKey | null>;
+    /**
+     * Replace an active key's limits (RFC 0004 A5); `{}` removes them. False when the tenant has no
+     * active key with that id. Throws `invalid_api_key_limits` for limits out of range.
+     */
+    setLimits(input: {
+        tenantRef: string;
+        id: string;
+        limits: SlotlockApiKeyLimits;
+    }): Promise<boolean>;
     /** Resolve a presented key to its tenant and scopes; null unless it is active. */
     authenticate(key: string): Promise<SlotlockApiKeyIdentity | null>;
     /**
@@ -111,8 +153,32 @@ export declare function slotlockApiKeyDigest(key: string): Buffer;
  * found key offline the same way; the server refuses a mistyped one without a lookup.
  */
 export declare function isSlotlockApiKey(value: string): boolean;
-/** A new key with the prefix lists show and the digest the database keeps. */
-export declare function generateSlotlockApiKey(): {
+/**
+ * A new key with the prefix lists show and the digest the database keeps; a test environment's
+ * (`test`) starts `slk_test_`.
+ */
+export declare function generateSlotlockApiKey(test?: boolean): {
+    key: string;
+    prefix: string;
+    digest: Buffer;
+};
+/**
+ * What a test environment's key starts with (RFC 0003 G9): it acts in `<tenant>~test`, a tenant of
+ * its own on its live tenant's plan, never billed.
+ */
+export declare const SLOTLOCK_TEST_API_KEY_PREFIX = "slk_test_";
+/** What ends a test environment's tenant reference: `<tenant>~test`. */
+export declare const SLOTLOCK_TEST_TENANT_SUFFIX = "~test";
+/** Whether the tenant is a test environment (`<tenant>~test`). */
+export declare function isSlotlockTestTenant(tenantRef: string): boolean;
+/** The live tenant of a test environment, or the tenant itself. */
+export declare function slotlockLiveTenant(tenantRef: string): string;
+/** What a partner key (RFC 0003 P1) starts with: never a tenant's key, which `slk_` and base62 follow. */
+export declare const SLOTLOCK_PARTNER_KEY_PREFIX = "slk_partner_";
+/** Whether `value` is shaped as a partner key with a matching checksum, as isSlotlockApiKey. */
+export declare function isSlotlockPartnerKey(value: string): boolean;
+/** A new partner key, with the prefix lists show (`slk_partner_` and 6 more) and its digest. */
+export declare function generateSlotlockPartnerKey(): {
     key: string;
     prefix: string;
     digest: Buffer;

package/api-keys.js

@@ -11,6 +11,7 @@ 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';
 import { isSlotlockChangeOrigin } from './event-feed.js';
+import { isSlotlockResourceScope } from './resource-profile.js';
 export { SLOTLOCK_API_KEY_ACTIVE_LIMIT, SLOTLOCK_API_KEY_RETAINED_LIMIT };
 /**
  * `read` covers the agent operations that only look; `write` the ones that change a calendar; `admin`
@@ -30,9 +31,7 @@ const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
 const RANDOM_CHARACTERS = 40;
 /** A 32-bit checksum fits in 6 base62 digits (62^6 > 2^32). */
 const CHECKSUM_CHARACTERS = 6;
-/** What lists show: the prefix and 8 random characters, enough to recognise a key, not to use it. */
-const DISPLAY_CHARACTERS = SLOTLOCK_API_KEY_PREFIX.length + 8;
-const KEY_PATTERN = /^slk_[0-9A-Za-z]{46}$/;
+const KEY_PATTERN = /^slk_(test_)?[0-9A-Za-z]{46}$/;
 /** The largest byte below 256 that is a multiple of 62, so `byte % 62` is unbiased below it. */
 const UNBIASED_BYTE_LIMIT = 248;
 const MAX_NAME_CHARACTERS = 100;
@@ -47,6 +46,52 @@ const DEFAULT_MAX_WAITING_LOOKUPS = 256;
 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;
+/** Whether `value` is a valid SlotlockApiKeyLimits. */
+export function isSlotlockApiKeyLimits(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const limits = value;
+    const known = new Set(['maxHolds', 'maxHeldHours', 'requestsPerMinute', 'requiresApproval']);
+    if (Object.keys(limits).some((key) => !known.has(key)))
+        return false;
+    const whole = (field, most) => field === undefined || (Number.isSafeInteger(field) && field >= 1 && field <= most);
+    return (whole(limits.maxHolds, 10_000) &&
+        whole(limits.maxHeldHours, 876_000) &&
+        whole(limits.requestsPerMinute, 100_000) &&
+        (limits.requiresApproval === undefined || typeof limits.requiresApproval === 'boolean'));
+}
+/** Limits as the database row has them, or undefined when the key has none. */
+function limitsFrom(row) {
+    const limits = {
+        ...(row.max_holds !== null ? { maxHolds: row.max_holds } : {}),
+        ...(row.max_held_hours !== null ? { maxHeldHours: row.max_held_hours } : {}),
+        ...(row.requests_per_minute !== null ? { requestsPerMinute: row.requests_per_minute } : {}),
+        ...(row.requires_approval === true ? { requiresApproval: true } : {}),
+    };
+    return Object.keys(limits).length > 0 ? limits : undefined;
+}
+const LIMITS_MESSAGE = 'Slotlock key limits are maxHolds (1-10,000), maxHeldHours (1-876,000), requestsPerMinute (1-100,000) and requiresApproval, each optional';
+function rowOfLimits(limits) {
+    return {
+        max_holds: limits.maxHolds ?? null,
+        max_held_hours: limits.maxHeldHours ?? null,
+        requests_per_minute: limits.requestsPerMinute ?? null,
+        requires_approval: limits.requiresApproval ?? null,
+    };
+}
+async function setKeyLimits(sql, tenantRef, id, limits) {
+    const row = rowOfLimits(limits);
+    const [set] = await sql `
+    SELECT slotlock.set_api_key_limits(
+      ${tenantRef}::text, ${id}::uuid, ${row.max_holds}::integer, ${row.max_held_hours}::integer,
+      ${row.requests_per_minute}::integer, ${row.requires_approval === true}::boolean) AS set`;
+    return set?.set === true;
+}
+/** A function the role was not granted, or that this database does not have yet. */
+function isNotGranted(error) {
+    const code = error?.code;
+    return code === '42501' || code === '42883';
+}
 function invalid(code, message) {
     return Object.assign(new Error(message), { code });
 }
@@ -104,20 +149,66 @@ export function slotlockApiKeyDigest(key) {
 export function isSlotlockApiKey(value) {
     if (typeof value !== 'string' || !KEY_PATTERN.test(value))
         return false;
-    const start = SLOTLOCK_API_KEY_PREFIX.length;
+    const start = value.startsWith(SLOTLOCK_TEST_API_KEY_PREFIX)
+        ? SLOTLOCK_TEST_API_KEY_PREFIX.length
+        : SLOTLOCK_API_KEY_PREFIX.length;
+    const random = value.slice(start, start + RANDOM_CHARACTERS);
+    return value.slice(start + RANDOM_CHARACTERS) === checksum(random);
+}
+/**
+ * A new key with the prefix lists show and the digest the database keeps; a test environment's
+ * (`test`) starts `slk_test_`.
+ */
+export function generateSlotlockApiKey(test = false) {
+    const random = randomBase62(RANDOM_CHARACTERS);
+    const start = test ? SLOTLOCK_TEST_API_KEY_PREFIX : SLOTLOCK_API_KEY_PREFIX;
+    const key = `${start}${random}${checksum(random)}`;
+    return { key, prefix: key.slice(0, start.length + 8), digest: slotlockApiKeyDigest(key) };
+}
+/**
+ * What a test environment's key starts with (RFC 0003 G9): it acts in `<tenant>~test`, a tenant of
+ * its own on its live tenant's plan, never billed.
+ */
+export const SLOTLOCK_TEST_API_KEY_PREFIX = 'slk_test_';
+/** What ends a test environment's tenant reference: `<tenant>~test`. */
+export const SLOTLOCK_TEST_TENANT_SUFFIX = '~test';
+/** Whether the tenant is a test environment (`<tenant>~test`). */
+export function isSlotlockTestTenant(tenantRef) {
+    return tenantRef.endsWith(SLOTLOCK_TEST_TENANT_SUFFIX);
+}
+/** The live tenant of a test environment, or the tenant itself. */
+export function slotlockLiveTenant(tenantRef) {
+    return isSlotlockTestTenant(tenantRef) ? tenantRef.slice(0, -SLOTLOCK_TEST_TENANT_SUFFIX.length) : tenantRef;
+}
+/** What a partner key (RFC 0003 P1) starts with: never a tenant's key, which `slk_` and base62 follow. */
+export const SLOTLOCK_PARTNER_KEY_PREFIX = 'slk_partner_';
+const PARTNER_KEY_PATTERN = /^slk_partner_[0-9A-Za-z]{46}$/;
+/** Whether `value` is shaped as a partner key with a matching checksum, as isSlotlockApiKey. */
+export function isSlotlockPartnerKey(value) {
+    if (typeof value !== 'string' || !PARTNER_KEY_PATTERN.test(value))
+        return false;
+    const start = SLOTLOCK_PARTNER_KEY_PREFIX.length;
     const random = value.slice(start, start + RANDOM_CHARACTERS);
     return value.slice(start + RANDOM_CHARACTERS) === checksum(random);
 }
-/** A new key with the prefix lists show and the digest the database keeps. */
-export function generateSlotlockApiKey() {
+/** A new partner key, with the prefix lists show (`slk_partner_` and 6 more) and its digest. */
+export function generateSlotlockPartnerKey() {
     const random = randomBase62(RANDOM_CHARACTERS);
-    const key = `${SLOTLOCK_API_KEY_PREFIX}${random}${checksum(random)}`;
-    return { key, prefix: key.slice(0, DISPLAY_CHARACTERS), digest: slotlockApiKeyDigest(key) };
+    const key = `${SLOTLOCK_PARTNER_KEY_PREFIX}${random}${checksum(random)}`;
+    return {
+        key,
+        prefix: key.slice(0, SLOTLOCK_PARTNER_KEY_PREFIX.length + 6),
+        digest: slotlockApiKeyDigest(key),
+    };
 }
 /** The credential of an `Authorization: Bearer <credential>` header, or undefined. */
 export function slotlockBearerCredential(request) {
     return /^Bearer +(\S+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
 }
+const canonicalResourceScope = (locations, groups) => ({
+    locations: [...new Set(locations)].sort(),
+    groups: [...new Set(groups)].sort(),
+});
 const knownScopes = (scopes) => SLOTLOCK_API_KEY_SCOPES.filter((scope) => scopes.includes(scope));
 function apiKeyFrom(row) {
     return {
@@ -177,6 +268,8 @@ async function asChange(sql, change, query) {
  * before a query runs; the functions and the table's constraints check the same rules again.
  */
 export function createSlotlockApiKeyStore(sql) {
+    // Whether the role may read key limits; a role granted before them may not, until granted again.
+    let limitsGranted = true;
     return {
         async create(input) {
             assertTenantRef(input.tenantRef);
@@ -187,6 +280,19 @@ export function createSlotlockApiKeyStore(sql) {
                 throw invalid('invalid_api_key_name', `Slotlock API key name must be 1-${MAX_NAME_CHARACTERS} characters without control characters`);
             }
             const scopes = canonicalScopes(input.scopes);
+            const resourceScope = input.resourceScope;
+            if (resourceScope !== undefined) {
+                if (!isSlotlockResourceScope(resourceScope)) {
+                    throw invalid('invalid_api_key_resource_scope', 'Slotlock key scope must name up to 20 locations and 20 groups by reference, at least one');
+                }
+                if (scopes.includes('admin')) {
+                    throw invalid('invalid_api_key_scopes', 'Slotlock keys limited to locations or groups read and write only: admin is the whole tenant');
+                }
+            }
+            const limits = input.limits;
+            if (limits !== undefined && !isSlotlockApiKeyLimits(limits)) {
+                throw invalid('invalid_api_key_limits', LIMITS_MESSAGE);
+            }
             const expiresAt = input.expiresAt;
             if (expiresAt !== undefined &&
                 (!(expiresAt instanceof Date) ||
@@ -203,35 +309,85 @@ export function createSlotlockApiKeyStore(sql) {
                     hasControlCharacter(createdBy))) {
                 throw invalid('invalid_api_key_creator', `Slotlock API key creator must be 1-${MAX_CREATOR_BYTES} bytes without control characters`);
             }
-            const { key, prefix, digest } = generateSlotlockApiKey();
+            const { key, prefix, digest } = generateSlotlockApiKey(isSlotlockTestTenant(input.tenantRef));
             // Scopes travel as one string: postgres.js binds `sql.array` as text[] only once the pool
             // has fetched the server's array types, which the first query on a new pool precedes.
-            const [row] = await asChange(sql, { ...(input.actor !== undefined ? { actor: input.actor } : {}), ...(input.origin ? { origin: input.origin } : {}) }, (tx) => tx `
-          SELECT * FROM slotlock.create_api_key(
-            ${input.tenantRef}::text,
-            ${name}::text,
-            ${prefix}::text,
-            ${digest}::bytea,
-            pg_catalog.string_to_array(${scopes.join(',')}::text, ','),
-            ${expiresAt ?? null}::timestamptz,
-            ${createdBy ?? null}::text
-          )`);
+            const [row] = await asChange(sql, { ...(input.actor !== undefined ? { actor: input.actor } : {}), ...(input.origin ? { origin: input.origin } : {}) }, async (tx) => {
+                const created = await tx `
+            SELECT * FROM slotlock.create_api_key(
+              ${input.tenantRef}::text,
+              ${name}::text,
+              ${prefix}::text,
+              ${digest}::bytea,
+              pg_catalog.string_to_array(${scopes.join(',')}::text, ','),
+              ${expiresAt ?? null}::timestamptz,
+              ${createdBy ?? null}::text
+            )`;
+                // In the same transaction: a limited key never exists without its limit.
+                if (created[0] && resourceScope) {
+                    await tx `
+              SELECT slotlock.set_api_key_resource_scope(
+                ${input.tenantRef}::text, ${created[0].key_id}::uuid,
+                pg_catalog.string_to_array(${resourceScope.locations.join(',')}::text, ','),
+                pg_catalog.string_to_array(${resourceScope.groups.join(',')}::text, ','))`;
+                }
+                if (created[0] && limits && limitsFrom(rowOfLimits(limits))) {
+                    await setKeyLimits(tx, input.tenantRef, created[0].key_id, limits);
+                }
+                return created;
+            });
             if (!row) {
-                throw invalid('api_key_limit_reached', `Slotlock allows ${SLOTLOCK_API_KEY_ACTIVE_LIMIT} active and ${SLOTLOCK_API_KEY_RETAINED_LIMIT} kept API keys per tenant; revoke one first`);
+                throw invalid('api_key_limit_reached', `Slotlock allows ${SLOTLOCK_API_KEY_ACTIVE_LIMIT} active and ${SLOTLOCK_API_KEY_RETAINED_LIMIT} kept API keys per tenant, or fewer active ones on a hosted plan; revoke one first`);
             }
-            return { key, apiKey: apiKeyFrom(row) };
+            const apiKey = apiKeyFrom(row);
+            if (resourceScope)
+                apiKey.resourceScope = canonicalResourceScope(resourceScope.locations, resourceScope.groups);
+            const kept = limits ? limitsFrom(rowOfLimits(limits)) : undefined;
+            if (kept)
+                apiKey.limits = kept;
+            return { key, apiKey };
+        },
+        async setLimits({ tenantRef, id, limits }) {
+            assertTenantRef(tenantRef);
+            if (typeof id !== 'string' || !UUID_PATTERN.test(id))
+                return false;
+            if (!isSlotlockApiKeyLimits(limits))
+                throw invalid('invalid_api_key_limits', LIMITS_MESSAGE);
+            return setKeyLimits(sql, tenantRef, id, limits);
         },
         async list({ tenantRef }) {
             assertTenantRef(tenantRef);
-            const rows = await sql `
-        SELECT * FROM slotlock.list_api_keys(${tenantRef}::text)`;
-            return rows.map(apiKeyFrom);
+            const [rows, limited, bounded] = await Promise.all([
+                sql `SELECT * FROM slotlock.list_api_keys(${tenantRef}::text)`,
+                sql `
+          SELECT key_id::text, locations, groups FROM slotlock.list_api_key_resource_scopes(${tenantRef}::text)`,
+                // A role granted before key limits cannot read them yet: its keys show none.
+                sql `
+          SELECT key_id::text, max_holds, max_held_hours, requests_per_minute, requires_approval
+            FROM slotlock.list_api_key_limits(${tenantRef}::text)`.catch((error) => {
+                    if (isNotGranted(error))
+                        return [];
+                    throw error;
+                }),
+            ]);
+            const scopes = new Map(limited.map((row) => [row.key_id, canonicalResourceScope(row.locations, row.groups)]));
+            const limitsByKey = new Map(bounded.map((row) => [row.key_id, limitsFrom(row)]));
+            return rows.map((row) => {
+                const apiKey = apiKeyFrom(row);
+                const scope = scopes.get(row.key_id);
+                if (scope)
+                    apiKey.resourceScope = scope;
+                const keyLimits = limitsByKey.get(row.key_id);
+                if (keyLimits)
+                    apiKey.limits = keyLimits;
+                return apiKey;
+            });
         },
         async rotate({ tenantRef, id, ...change }) {
             assertTenantRef(tenantRef);
             if (typeof id !== 'string' || !UUID_PATTERN.test(id))
                 return null;
-            const { key, prefix, digest } = generateSlotlockApiKey();
+            const { key, prefix, digest } = generateSlotlockApiKey(isSlotlockTestTenant(tenantRef));
             const [row] = await asChange(sql, change, (tx) => tx `
         SELECT * FROM slotlock.rotate_api_key(
           ${tenantRef}::text, ${id}::uuid, ${prefix}::text, ${digest}::bytea
@@ -249,11 +405,42 @@ export function createSlotlockApiKeyStore(sql) {
         async authenticate(key) {
             if (!isSlotlockApiKey(key))
                 return null;
-            const [row] = await sql `
-        SELECT * FROM slotlock.authenticate_api_key(${slotlockApiKeyDigest(key)}::bytea)`;
+            const digest = slotlockApiKeyDigest(key);
+            let row;
+            if (limitsGranted) {
+                try {
+                    [row] = await sql `SELECT * FROM slotlock.authenticate_limited_api_key(${digest}::bytea)`;
+                }
+                catch (error) {
+                    // A role granted before key limits (grantApplicationRole not run again since): keys
+                    // still authenticate, without limits, and this process stops asking.
+                    if (!isNotGranted(error))
+                        throw error;
+                    limitsGranted = false;
+                }
+            }
+            if (!limitsGranted) {
+                [row] = await sql `SELECT * FROM slotlock.authenticate_scoped_api_key(${digest}::bytea)`;
+            }
             if (!row)
                 return null;
-            return { id: row.key_id, tenantRef: row.key_tenant_ref, scopes: knownScopes(row.key_scopes) };
+            const identity = {
+                id: row.key_id,
+                tenantRef: row.key_tenant_ref,
+                scopes: knownScopes(row.key_scopes),
+            };
+            if (row.scope_locations !== null || row.scope_groups !== null) {
+                identity.resourceScope = canonicalResourceScope(row.scope_locations ?? [], row.scope_groups ?? []);
+            }
+            const keyLimits = limitsFrom({
+                max_holds: row.max_holds ?? null,
+                max_held_hours: row.max_held_hours ?? null,
+                requests_per_minute: row.requests_per_minute ?? null,
+                requires_approval: row.requires_approval ?? null,
+            });
+            if (keyLimits)
+                identity.limits = keyLimits;
+            return identity;
         },
         async erase({ tenantRef }) {
             assertTenantRef(tenantRef);
@@ -326,6 +513,8 @@ export function createSlotlockApiKeyAuthenticator(keys, options = {}) {
                 tenantRef: identity.tenantRef,
                 scopes: identity.scopes,
                 keyId: identity.id,
+                ...(identity.resourceScope ? { resourceScope: identity.resourceScope } : {}),
+                ...(identity.limits ? { limits: identity.limits } : {}),
             };
         }
         finally {

package/application-api.d.ts

@@ -2,9 +2,13 @@ import { type SlotlockChangeOrigin } from './event-feed.js';
 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_export_resource_availability' | 'slotlock_import_resource_availability' | 'slotlock_set_resource_booking_rules' | 'slotlock_set_resource_pool' | 'slotlock_list_pools' | 'slotlock_get_booking_rule_defaults' | 'slotlock_set_tenant_booking_rules' | 'slotlock_set_pool_booking_rules' | '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 type SlotlockApplicationOperation = 'slotlock_create_resource' | 'slotlock_update_resource' | 'slotlock_list_locations' | 'slotlock_create_location' | 'slotlock_update_location' | 'slotlock_delete_location' | 'slotlock_list_groups' | 'slotlock_create_group' | 'slotlock_delete_group' | 'slotlock_add_group_member' | 'slotlock_remove_group_member' | '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_set_resource_parent' | 'slotlock_list_pools' | 'slotlock_set_pool_order' | 'slotlock_get_booking_rule_defaults' | 'slotlock_set_tenant_booking_rules' | 'slotlock_set_pool_booking_rules' | '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' | 'slotlock_get_usage' | 'slotlock_list_approval_policies' | 'slotlock_put_approval_policy' | 'slotlock_delete_approval_policy' | 'slotlock_list_approvals' | 'slotlock_get_approval' | 'slotlock_decide_approval' | 'slotlock_sandbox_seed' | 'slotlock_sandbox_reset' | 'slotlock_sandbox_fast_forward' | 'slotlock_sandbox_race' | 'slotlock_partner_put_account' | 'slotlock_partner_list_accounts' | 'slotlock_partner_get_account' | 'slotlock_partner_list_keys' | 'slotlock_partner_create_key' | 'slotlock_partner_rotate_key' | 'slotlock_partner_revoke_key' | 'slotlock_partner_suspend_account' | 'slotlock_partner_unsuspend_account' | 'slotlock_partner_erase_account' | 'slotlock_partner_get_usage' | 'slotlock_partner_reconcile_usage';
+/** The scope an application operation needs, but the partner API's (`slotlockApplicationScope`). */
 export declare const SLOTLOCK_APPLICATION_SCOPE = "admin";
+/** The scope one application operation needs: `partner` for the partner API's, else `admin`. */
+export declare function slotlockApplicationScope(definition: {
+    scope?: 'partner';
+}): string;
 export interface SlotlockApplicationInvocationContext {
     principal: SlotlockAgentPrincipal;
     operation: SlotlockApplicationOperation;
@@ -13,7 +17,16 @@ export interface SlotlockApplicationInvocationContext {
     trace?: SlotlockTraceContext;
     /** The surface the call came through: `application` when the agent server dispatches it. */
     origin?: SlotlockChangeOrigin;
+    /** A dry run (RFC 0004 A3): every check, then rolled back (SlotlockAgentInvocationContext). */
+    dryRun?: boolean;
 }
+/** Whether an application operation takes `dry_run` (RFC 0004 A3): a write that can be undone. */
+export declare function slotlockApplicationDryRunnable(definition: {
+    name: string;
+    risk: {
+        readOnly: boolean;
+    };
+}): boolean;
 type Handler = (context: SlotlockApplicationInvocationContext, input: Record<string, unknown>) => Promise<Record<string, unknown>>;
 /**
  * What serves the application operations: each method gets schema-valid input and returns what its
@@ -22,6 +35,16 @@ type Handler = (context: SlotlockApplicationInvocationContext, input: Record<str
  */
 export interface SlotlockApplicationBackend {
     createResource: Handler;
+    updateResource: Handler;
+    listLocations: Handler;
+    createLocation: Handler;
+    updateLocation: Handler;
+    deleteLocation: Handler;
+    listGroups: Handler;
+    createGroup: Handler;
+    deleteGroup: Handler;
+    addGroupMember: Handler;
+    removeGroupMember: Handler;
     getResource: Handler;
     archiveResource: Handler;
     restoreResource: Handler;
@@ -33,7 +56,9 @@ export interface SlotlockApplicationBackend {
     importResourceAvailability: Handler;
     setResourceBookingRules: Handler;
     setResourcePool: Handler;
+    setResourceParent: Handler;
     listPools: Handler;
+    setPoolOrder: Handler;
     getBookingRuleDefaults: Handler;
     setTenantBookingRules: Handler;
     setPoolBookingRules: Handler;
@@ -69,12 +94,35 @@ export interface SlotlockApplicationBackend {
     listWebhooks: Handler;
     deleteWebhook: Handler;
     enableWebhook: Handler;
+    getUsage: Handler;
+    listApprovalPolicies: Handler;
+    putApprovalPolicy: Handler;
+    deleteApprovalPolicy: Handler;
+    listApprovals: Handler;
+    getApproval: Handler;
+    decideApproval: Handler;
+    sandboxSeed: Handler;
+    sandboxReset: Handler;
+    sandboxFastForward: Handler;
+    sandboxRace: Handler;
+    partnerPutAccount: Handler;
+    partnerListAccounts: Handler;
+    partnerGetAccount: Handler;
+    partnerListKeys: Handler;
+    partnerCreateKey: Handler;
+    partnerRotateKey: Handler;
+    partnerRevokeKey: Handler;
+    partnerSuspendAccount: Handler;
+    partnerUnsuspendAccount: Handler;
+    partnerEraseAccount: Handler;
+    partnerGetUsage: Handler;
+    partnerReconcileUsage: Handler;
 }
 export interface SlotlockApplicationOperationDefinition {
     name: SlotlockApplicationOperation;
     title: string;
     description: string;
-    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | '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>>;
@@ -85,6 +133,11 @@ export interface SlotlockApplicationOperationDefinition {
         idempotent: boolean;
     };
     invoke: keyof SlotlockApplicationBackend;
+    /**
+     * The scope the operation needs: `admin` (SLOTLOCK_APPLICATION_SCOPE) unless it is the partner
+     * API's, which needs a partner key's `partner` (RFC 0003 P3) and nothing else reaches.
+     */
+    scope?: 'partner';
     /** Valid input, path parameters included (a test runs each against the schema). */
     example: Record<string, unknown>;
 }