slotlock 0.8.0 → 0.10.0

package/maintenance.js

@@ -1,5 +1,6 @@
 import { ignoreRejection } from './hooks.js';
-import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, calendarEventRollingHorizon, } from './store.js';
+import { SLOTLOCK_MAX_WAITLIST_PER_TENANT, buildSlotlockTenantExport, calendarEventRollingHorizon, } from './store.js';
+import { readSlotlockHolidayCalendar } from './holiday-import.js';
 /**
  * One maintenance pass for a tenant: roll its recurring events to the horizon, then purge expired
  * holds and prune bookkeeping past retention, each in at most `batches` batches (1-100, default
@@ -72,12 +73,25 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
     options.signal?.throwIfAborted();
     // Conversations expire 2 hours after their last message (dashboard.ts).
     pruned += await withTenant((tenant) => tenant.pruneAssistantConversations({ tenantRef }));
+    // Audit events past retention (SLOTLOCK_AUDIT_RETENTION_DAYS, 180).
+    pruned += await withTenant((tenant) => tenant.pruneAuditEvents({ tenantRef }));
+    // Exports past their time go; one a stopped server left pending is built now (RFC 0004 D3).
+    const exports = await withTenant((tenant) => tenant.pruneTenantExports({ tenantRef }));
+    pruned += exports.deleted;
+    for (const exportId of exports.pending) {
+        options.signal?.throwIfAborted();
+        await buildSlotlockTenantExport(store, tenantRef, exportId);
+    }
     const zones = await withTenant((tenant) => tenant.followZoneRules({ tenantRef, move: options.followZoneRules === true }));
     const staleSources = await withTenant((tenant) => tenant.reportStaleCoverage({ tenantRef }));
     // Approvals past their wait, and no-shows, first: the time they free is offered to the waitlist
     // in the same pass.
     const approvals = await withTenant((tenant) => tenant.expireApprovals({ tenantRef, limit: 100 }));
     const noShows = await withTenant((tenant) => tenant.releaseNoShows({ tenantRef }));
+    // Bookings that ended since the last pass (RFC 0004 B4): no row changes, the feed says so.
+    const completed = await withTenant((tenant) => tenant.completeEndedBookings({ tenantRef, limit: 500 }));
+    const reminders = await withTenant((tenant) => tenant.dueReminders({ tenantRef, limit: 500 }));
+    const holidays = options.holidayFetch ? await importDueHolidayCalendars(withTenant, tenantRef, options) : 0;
     // The whole waitlist in join order, a page per transaction, so a later free entry is offered
     // however many wait before it.
     let waitlistOffers = 0;
@@ -103,10 +117,58 @@ export async function maintainSlotlockTenant(store, tenantRef, options = {}) {
         noShows,
         waitlistOffers,
         approvalsExpired: approvals.expired,
-        capped: rollCapped || eventsLeft || bookingsLeft || changesLeft || approvals.expired === 100,
+        bookingsCompleted: completed,
+        remindersDue: reminders,
+        holidayCalendarsImported: holidays,
+        capped: rollCapped ||
+            eventsLeft ||
+            bookingsLeft ||
+            changesLeft ||
+            approvals.expired === 100 ||
+            completed === 500 ||
+            reminders === 500,
         rollPending: rollCapped && after !== null && (after.rollRetryAt ?? null) === null,
     };
 }
+/** Holiday calendar subscriptions imported again in one pass, at most: each is a fetch. */
+const HOLIDAY_IMPORTS_PER_PASS = 5;
+/**
+ * Import again the tenant's holiday calendar subscriptions that are due: each fetched outside any
+ * transaction, then imported in one; one that cannot be read or imported keeps its closures and
+ * notes why, to be tried again a day later.
+ */
+async function importDueHolidayCalendars(withTenant, tenantRef, options) {
+    const due = await withTenant((tenant) => tenant.dueHolidayCalendars({ tenantRef, limit: HOLIDAY_IMPORTS_PER_PASS }));
+    let imported = 0;
+    for (const calendar of due) {
+        options.signal?.throwIfAborted();
+        if (!calendar.url)
+            continue;
+        try {
+            const read = await readSlotlockHolidayCalendar({ url: calendar.url, subscribe: true, name: calendar.name }, options.holidayFetch);
+            await withTenant((tenant) => tenant.importHolidayCalendar({
+                tenantRef,
+                ...(calendar.location !== undefined ? { location: calendar.location } : {}),
+                ...(calendar.resourceId !== undefined ? { resourceId: calendar.resourceId } : {}),
+                name: calendar.name,
+                ...(read.url !== undefined ? { url: read.url } : {}),
+                holidays: read.holidays,
+                span: read.span,
+            }));
+            imported++;
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw error;
+            await withTenant((tenant) => tenant.noteHolidayCalendarFailure({
+                tenantRef,
+                id: calendar.id,
+                error: error instanceof Error ? error.message : 'The import failed',
+            }));
+        }
+    }
+    return imported;
+}
 /** Pages of 50 that cover a tenant's whole waitlist (SLOTLOCK_MAX_WAITLIST_PER_TENANT). */
 const WAITLIST_PAGES = Math.ceil(SLOTLOCK_MAX_WAITLIST_PER_TENANT / 50);
 /** How often the scheduler sweeps every tenant's expired assistant conversations, at most. */
@@ -183,6 +245,7 @@ export function startSlotlockMaintenance(options) {
                     const result = await withSlotlockMaintenanceLock(options.sql, tenantRef, () => maintainSlotlockTenant(options.store, tenantRef, {
                         ...(options.batches !== undefined ? { batches: options.batches } : {}),
                         ...(options.usage ? { usage: true } : {}),
+                        ...(options.holidayFetch ? { holidayFetch: options.holidayFetch } : {}),
                         signal: controller.signal,
                     }));
                     recordPass(tenantRef, Date.now());
@@ -239,6 +302,11 @@ export function startSlotlockMaintenance(options) {
             return;
         lastSweep = Date.now();
         options.store.sweepAssistantConversations().catch(report);
+        // Team invitations finished a month ago, with the addresses they were sent to, and sessions
+        // ended a day ago.
+        options.store.sweepDashboardRecords().catch(report);
+        // Verified domains whose daily check (or a pending claim's hourly one) is due.
+        options.domainChecks?.().catch(report);
     };
     // Every tenant with data, once an interval: those no key has called since the server started too.
     let lastDiscovery = Number.NEGATIVE_INFINITY;

package/metrics.js

@@ -19,6 +19,9 @@ const MAINTENANCE_COUNTS = [
     'noShows',
     'waitlistOffers',
     'approvalsExpired',
+    'bookingsCompleted',
+    'remindersDue',
+    'holidayCalendarsImported',
 ];
 /** A label value: an operation, protocol or outcome code. Anything else is counted as `other`. */
 const LABEL = /^[a-z0-9_.]{1,64}$/;

package/oidc.d.ts

@@ -0,0 +1,135 @@
+/** The algorithms Slotlock verifies: RSA PKCS#1 v1.5, RSA-PSS and ECDSA P-256, all with SHA-256. */
+export declare const SLOTLOCK_OIDC_ALGORITHMS: readonly ["RS256", "PS256", "ES256"];
+export type SlotlockOidcAlgorithm = (typeof SLOTLOCK_OIDC_ALGORITHMS)[number];
+/** Why an ID token was refused (never shown with the token). */
+export type SlotlockIdTokenRefusal = 'malformed' | 'algorithm' | 'key' | 'signature' | 'issuer' | 'audience' | 'expired' | 'not_yet_valid' | 'issued_at' | 'nonce' | 'subject';
+/** RFC 4648 base64url, without padding, to bytes; null when it is not that. */
+export declare function slotlockBase64UrlBytes(text: string): Uint8Array<ArrayBuffer> | null;
+/** Bytes as RFC 4648 base64url, without padding. */
+export declare function slotlockBase64Url(bytes: Uint8Array): string;
+/** A JWK as an issuer publishes it. */
+export interface SlotlockJwk {
+    kty?: unknown;
+    kid?: unknown;
+    use?: unknown;
+    alg?: unknown;
+    n?: unknown;
+    e?: unknown;
+    crv?: unknown;
+    x?: unknown;
+    y?: unknown;
+}
+/**
+ * A published key as a verification key for `alg`, or null when it does not fit it: RSA (at least
+ * 2048 bits) for RS256 and PS256, EC P-256 for ES256; `use`, when given, `sig`; `alg`, when given,
+ * the token's.
+ */
+export declare function importSlotlockJwk(jwk: SlotlockJwk, alg: SlotlockOidcAlgorithm): Promise<CryptoKey | null>;
+/** Finds the key a token names: by issuer's JWKS and key id (see createSlotlockJwksCache). */
+export type SlotlockKeyLookup = (kid: string | null, alg: SlotlockOidcAlgorithm) => Promise<CryptoKey | null>;
+/** What an ID token is checked against. */
+export interface SlotlockIdTokenExpectation {
+    /** The exact issuer, or the exact spellings one issuer documents (Google has two). */
+    issuers: readonly string[];
+    clientId: string;
+    /** The algorithms this issuer may sign with: a subset of SLOTLOCK_OIDC_ALGORITHMS. */
+    algorithms: readonly SlotlockOidcAlgorithm[];
+    keys: SlotlockKeyLookup;
+    nonce: string;
+    /** Milliseconds since the epoch. */
+    now: number;
+}
+/** An ID token checked: its claims, all of them, for the caller to read what it needs. */
+export type SlotlockIdTokenResult = {
+    claims: Record<string, unknown>;
+} | {
+    refusal: SlotlockIdTokenRefusal;
+};
+/** Check an ID token: its signature first, then its claims, in OpenID Connect Core's order. */
+export declare function verifySlotlockIdToken(token: string, expected: SlotlockIdTokenExpectation): Promise<SlotlockIdTokenResult>;
+/** Why a URL an Owner gave, or a document fetched from one, was refused. */
+export declare class SlotlockOidcFetchError extends Error {
+    readonly code: 'url' | 'redirect' | 'status' | 'type' | 'size' | 'json' | 'network';
+    constructor(code: 'url' | 'redirect' | 'status' | 'type' | 'size' | 'json' | 'network', message: string);
+}
+/**
+ * Whether a URL is one Slotlock fetches for a team: https on the default port, a host name (never
+ * an IP literal), never localhost, a single label, or a private-use suffix; no credentials.
+ */
+export declare function slotlockOidcUrlAllowed(value: string): URL | null;
+/**
+ * GET a JSON document from a URL an Owner influenced: refused unless slotlockOidcUrlAllowed; no
+ * redirect followed (any 3xx refuses); 5 seconds; 256 KB; a JSON content type. On Node, pass a
+ * fetch that refuses private addresses (webhooks.ts createSlotlockGuardedFetch).
+ */
+export declare function slotlockFetchOidcJson(value: string, options?: {
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    maxBytes?: number;
+}): Promise<{
+    body: Record<string, unknown>;
+    maxAge: number | null;
+}>;
+/**
+ * A JSON object answered by a host an Owner chose, read to at most maxBytes (the declared length
+ * first, then as it streams), so a provider cannot make the server buffer an endless answer.
+ */
+export declare function slotlockReadJsonBody(response: Response, maxBytes: number): Promise<Record<string, unknown>>;
+/** An issuer's endpoints, as its discovery document gave them when an Owner saved the connection. */
+export interface SlotlockOidcProvider {
+    issuer: string;
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    jwksUri: string;
+    algorithms: SlotlockOidcAlgorithm[];
+    /** RFC 9207: the issuer returns `iss` with the code, and Slotlock then checks it. */
+    issParameter: boolean;
+}
+/**
+ * An issuer's discovery document (OpenID Connect Discovery 1.0): its `issuer` must be exactly the
+ * one entered, its endpoints https on public host names, and it must sign with an algorithm Slotlock
+ * verifies.
+ */
+export declare function discoverSlotlockOidc(issuer: string, options?: {
+    fetch?: typeof fetch;
+}): Promise<SlotlockOidcProvider>;
+/**
+ * An Entra ID tenant's v2.0 issuer, pinned to its GUID: never `common`, `organizations`,
+ * `consumers`, a domain name or the consumer tenant, so the multi-tenant `{tenantid}` issuer never
+ * exists in Slotlock. Null when the tenant is not one.
+ */
+export declare function slotlockEntraIssuer(tenant: string): string | null;
+/** Google's issuer, in the two spellings it documents. */
+export declare const SLOTLOCK_GOOGLE_ISSUERS: readonly string[];
+/**
+ * Issuers' keys, by JWKS URL: kept for the answer's max-age (5 minutes to 24 hours). A key id not
+ * among them is fetched again at most once a minute per URL, one fetch at a time; while the URL
+ * fails, a set fetched within 24 hours still serves the keys it holds. At most `maxUrls` URLs and 20
+ * keys each are kept, only the fields verifying needs: the URLs are Owners' to choose.
+ */
+export declare function createSlotlockJwksCache(options: {
+    fetchJson?: (url: string) => Promise<{
+        body: Record<string, unknown>;
+        maxAge: number | null;
+    }>;
+    fetch?: typeof fetch;
+    now?: () => number;
+    /** How many JWKS URLs are kept (100): the least recently used goes first. */
+    maxUrls?: number;
+}): {
+    /** The key `kid` names at `url` for `alg`, or null. */
+    key(url: string, kid: string | null, alg: SlotlockOidcAlgorithm): Promise<CryptoKey | null>;
+    /** A lookup bound to one JWKS URL, for verifySlotlockIdToken. */
+    lookup(url: string): SlotlockKeyLookup;
+};
+export type SlotlockJwksCache = ReturnType<typeof createSlotlockJwksCache>;
+/**
+ * Seals and opens a team's client secret: AES-256-GCM under a key derived (HKDF-SHA-256) from
+ * SLOTLOCK_SSO_SECRET, a random 12-byte IV each time, and the team and connection as associated
+ * data, so a sealed secret moved to another row does not open.
+ */
+export declare function createSlotlockSecretBox(secret: string): {
+    seal(plaintext: string, associated: string): Promise<string>;
+    open(sealed: string, associated: string): Promise<string | null>;
+};
+export type SlotlockSecretBox = ReturnType<typeof createSlotlockSecretBox>;