slotlock 0.5.2 → 0.6.0

package/SECURITY.md

@@ -22,19 +22,12 @@ Do not include real customer, credential, calendar, or booking data. We will ack
 within three business days and coordinate disclosure after a fix is available. Fixed vulnerabilities
 are published as advisories at <https://github.com/PILOTAAI/slotlock/security/advisories>.
 
-## Testing hosted Slotlock
+## Hosted Slotlock
 
-Hosted Slotlock (`slotlock-api.pylota.io` and `app.slotlock.pylota.io`, run by TREFT LTD) is in scope,
-under these rules, which its [Terms of Service](TERMS.md) and
-[Acceptable Use Policy](ACCEPTABLE-USE.md) refer to:
-
-- Test only against an account of your own, signed in with your own GitHub account.
-- Never read, change or keep another account's data. If a test reaches any, stop and report it at
-  once, and delete what you saw.
-- Run no denial of service, load test or automated scanning that sends more than the published
-  limits ([hosted service page](docs/hosted/README.md#limits)); run Slotlock yourself for that.
-- Report through private vulnerability reporting as above, and give us the time to fix it before
-  you disclose anything.
+The hosted service is not open; self-hosting is the only supported path today. Do not test
+`slotlock-api.pylota.io` or `app.slotlock.pylota.io`: they are not in scope until this section
+says the service is open and gives the rules for testing it. Test Slotlock by running it yourself,
+and report what you find as above.
 
 ## Security model
 
@@ -84,7 +77,10 @@ earlier, `PUBLIC` may still hold `CREATE` on `public`; the check then refuses ev
 a lock that blocks other tenants: that is availability, not isolation. `slotlock serve` checks the
 role it connects as before it serves, and refuses to start as a superuser or a `BYPASSRLS` role
 (`unsafe_serving_role`); it does not repeat the rest of this check, so that a single owning role can
-still migrate and serve (`serve --migrate` without `SLOTLOCK_MIGRATE_DATABASE_URL`).
+still migrate and serve (`serve --migrate` without `SLOTLOCK_MIGRATE_DATABASE_URL`). Row-level
+security does not confine the owner on tables that do not force it, and the owner can lift it, so
+`serve` logs a `serving_as_schema_owner` warning at startup when its role owns the `slotlock`
+schema: serve as a role that owns nothing in production.
 
 Schema changes run under a separate deployment role, which must own the `slotlock` schema and every
 object in it (`applySchema` creates the schema when it is missing). The deployment writes rows into
@@ -105,6 +101,23 @@ as the deployment role or a superuser, or trust its owner as much. `SLOTLOCK_COR
 caller's `search_path` at their end; apply each in one transaction (`psql --single-transaction`),
 since under autocommit the pin ends with the statement that sets it.
 
+The change feed, the history and webhooks name a coverage source by its `source_id`, never the
+source itself, which can be an iCalendar URL with a token or an address. The id is random (`src_` and
+32 hex digits from `gen_random_uuid()`), stored with the source when it is first recorded and kept
+until it is deleted, so someone who sees a change and knows the tenant cannot confirm a guessed
+source against it (0.5.3's id was an unkeyed digest of the tenant and the source, and could be).
+The tenant reads the id beside the source from `listCoverage`. Upgrading renames the coverage
+changes earlier releases wrote, which carried the source, its last error or that digest, and a
+trigger on the outbox puts one an earlier release's server (0.3-0.5) still running writes after the
+upgrade in the same shape as it is inserted, so none is stored with its source. Every read path serves a `coverage.*` change without `source` and `last_error`, named
+`src_redacted` when its subject is not such an id, and history by subject never matches a coverage
+change by any other name. What was already sent stays sent: a webhook receiver keeps an earlier
+delivery, so rotate a token that an earlier release delivered in a `coverage.stale` change. A
+0.5.3 `source_id` already forwarded (a webhook delivery, a feed reader's copy, a log) still reveals
+its source to anyone who guesses the source and knows the tenant, as it did then; the rename changes
+only the copies in the outbox. `slotlockCoverageSourceId`, which worked that digest out, throws
+since 0.6.
+
 The privacy-minimised provider parser cannot return summaries, locations, notes, organizers or
 attendees. Full event parsing is a separate trusted API and must only receive authenticated content.
 Event command rows retain payload digests and stable results, never duplicate event content. Event

package/SPEC.md

@@ -245,13 +245,16 @@ envelope (a body over the size limit is HTTP 413); A2A's own errors, below, carr
 `google.rpc.ErrorInfo` detail and JSON-RPC's (`-32700`, `-32600`, `-32601`, `-32603`) none. An
 `A2A-Version` other than `1.0`, including none (read as 0.3), is `VersionNotSupportedError`
 (`-32009`); push-notification methods are
-`PushNotificationNotSupportedError` (`-32003`); streaming, task subscription and the extended card
-are `UnsupportedOperationError` (`-32004`); a message that is not exactly one data part
+`PushNotificationNotSupportedError` (`-32003`); task subscription and the extended card are
+`UnsupportedOperationError` (`-32004`); a message that is not exactly one data part
 `{"skill": "<id>", "arguments": {…}}` (`arguments` left out or null is none; any other value that is
 not an object is not arguments) is `-32602`, as is a `configuration` or `metadata` that is set but
 is not an object; a rate-limited request is `-32029` with the reason `RATE_LIMITED` and a null id,
-answered before its body is read. The server replies with messages and keeps no
-tasks, so the core task operations answer as for an unknown task: `GetTask` and `CancelTask` are
+answered before its body is read. `SendStreamingMessage` streams a skill's reply as one message;
+with `slotlock_watch_resources` it streams a watch task (TASK_STATE_WORKING, a status update per
+changed resource, then TASK_STATE_COMPLETED or TASK_STATE_FAILED) that lives only in its stream,
+under the MCP subscription caps; refused before it opens, it is the skill's reply. The server keeps
+no tasks, so the core task operations answer as for an unknown task: `GetTask` and `CancelTask` are
 `TaskNotFoundError` (`-32001`), `ListTasks` returns an empty page (`pageSize` 1-100, default 50).
 Their params are checked first, as `SendMessage`'s are: a field the method does not define, a
 `tenant` other than the caller's, a value of the wrong type (a `status` outside `TaskState`, say), a
@@ -364,9 +367,9 @@ with no remaining command; `internal` tombstones remain authoritative until tena
 command evaluated after its evidence is gone is decided afresh by the expected-revision guard.
 
 The protocol backend remains injectable so a deployment owns credential verification, policy, rate
-limits, and networking. The A2A binding is intentionally synchronous and advertises neither
-streaming nor push notifications; an embedder must not claim task lifecycle support unless it
-persists that lifecycle itself.
+limits, and networking. The A2A binding advertises streaming (a reply as one message, a watch as
+a task that lives only in its stream) and not push notifications; an embedder must not claim
+persisted task lifecycle support unless it persists that lifecycle itself.
 
 The optional Node HTTP adapter preserves the Fetch boundary rather than defining another protocol
 implementation. It constructs callback-visible request URLs from an explicit canonical origin,

package/agent-server.d.ts

@@ -1,5 +1,7 @@
 import { type SlotlockTraceContext } from './mcp-modern.js';
 import { type SlotlockApplicationBackend, type SlotlockApplicationOperation } from './application-api.js';
+import { type SlotlockAgentChangeSource } from './change-watch.js';
+import type { SlotlockChangeOrigin } from './event-feed.js';
 export type { SlotlockTraceContext } from './mcp-modern.js';
 export { clientSupportsSlotlockMcpApp, SLOTLOCK_MCP_APP_HTML, SLOTLOCK_MCP_APP_MIME_TYPE, SLOTLOCK_MCP_APP_RESOURCE, SLOTLOCK_MCP_APP_RESOURCE_URI, SLOTLOCK_MCP_APPS_EXTENSION, } from './mcp-app.js';
 /**
@@ -64,6 +66,11 @@ export interface SlotlockAgentPrincipal {
      * Unset, `authorize` alone decides.
      */
     scopes?: readonly string[];
+    /**
+     * The API key the credential is, by its id (a UUID), when it is one: the history records it with
+     * each change the principal makes (`createSlotlockApiKeyAuthenticator` sets it).
+     */
+    keyId?: string;
 }
 export interface SlotlockAgentInvocationContext {
     principal: SlotlockAgentPrincipal;
@@ -74,6 +81,11 @@ export interface SlotlockAgentInvocationContext {
      * backend's spans as its children to follow one agent action across services.
      */
     trace?: SlotlockTraceContext;
+    /**
+     * The surface the call came through (`mcp`, `a2a`, `rest`, `dashboard-assistant`), for a backend
+     * to record with its changes (withTenant's `origin`).
+     */
+    origin?: SlotlockChangeOrigin;
 }
 /** A bounded domain failure a backend may deliberately expose through a protocol tool result. */
 export declare class SlotlockAgentOperationError extends Error {
@@ -182,13 +194,27 @@ export interface SlotlockAgentConfirmationOptions {
 /**
  * Live calendar updates over MCP 2026-07-28 `subscriptions/listen`. A client subscribes to calendar
  * resource URIs (`slotlockCalendarResourceUri`) and receives `notifications/resources/updated` on the
- * response stream when a resource's free/busy changes. The server finds changes by re-reading each
- * open subscription's resources through the backend every `pollIntervalMs`, re-running `authenticate`
- * and `authorize` each time, so a revoked credential or permission ends the stream.
+ * response stream when a resource's free/busy changes. With `changes`, the server follows each
+ * tenant's change feed (one reader per tenant, shared by all its subscriptions) and re-reads a
+ * subscription's resources when a change touches one of them; without it, it re-reads them every
+ * `pollIntervalMs`. Each re-read runs `authenticate` and `authorize` again, so a revoked credential
+ * or permission ends the stream, and announces only the resources whose free/busy changed.
  */
 export interface SlotlockAgentSubscriptionOptions {
-    /** How often an open subscription re-reads its resources, in ms: 1,000-300,000, default 10,000. */
+    /**
+     * How often an open subscription re-reads its resources regardless, in ms: 1,000-300,000. Default
+     * 10,000, or 15,000 with `changes`, where it is the fallback for what the feed does not carry
+     * (bookable hours, a revoked key or permission) and for a feed that stopped.
+     */
     pollIntervalMs?: number;
+    /**
+     * The change feed to follow (createSlotlockStoreChangeSource, or your own over
+     * SlotlockEventFeed.listChanges), polled by one reader per tenant every SLOTLOCK_FEED_BUSY_MS to
+     * SLOTLOCK_FEED_IDLE_MS: a change is announced within about a second instead of at the next
+     * re-read. A subscription re-reads its resources at most once a second, however many changes
+     * touch them.
+     */
+    changes?: SlotlockAgentChangeSource;
     /** When the server ends a subscription gracefully, in ms: 60,000-86,400,000, default 900,000. */
     maxDurationMs?: number;
     /** How often a quiet stream carries an SSE keep-alive comment, in ms: 1,000-60,000, default 15,000. */
@@ -348,6 +374,12 @@ export interface SlotlockAgentOperationDispatchOptions {
     /** As `SlotlockAgentServerOptions.onError`: a failure the result reports only as internal. */
     onError?: (error: unknown, context: SlotlockAgentErrorContext) => void;
 }
+/** One reason `invalid_arguments` refused a call: where in the arguments, and what is wrong there. */
+export interface SlotlockArgumentIssue {
+    /** The field's path in the arguments, outermost first (`["rules", 0, "rrule"]`); `[]` is the arguments as a whole. */
+    path: (string | number)[];
+    message: string;
+}
 export type SlotlockAgentOperationDispatchResult = {
     ok: true;
     data: Record<string, unknown>;
@@ -356,6 +388,8 @@ export type SlotlockAgentOperationDispatchResult = {
     status: number;
     code: string;
     details?: Readonly<Record<string, string>>;
+    /** With `invalid_arguments` from argument validation: the fields it refused. */
+    issues?: readonly SlotlockArgumentIssue[];
 };
 /** Runtime type guard for the current operation names (legacy dotted names are not included). */
 export declare function isSlotlockAgentOperation(name: unknown): name is SlotlockAgentOperation;
@@ -393,6 +427,7 @@ export declare function slotlockMcpToolResult(outcome: {
     ok: false;
     code: string;
     details?: Readonly<Record<string, string | number | boolean | null>>;
+    issues?: readonly SlotlockArgumentIssue[];
 }): SlotlockMcpToolResult;
 /** The application operations with their input and output as JSON Schema, as REST serves them. */
 export declare function slotlockApplicationOperations(): {
@@ -449,6 +484,8 @@ export declare function invokeSlotlockAgentOperation(args: {
     options: SlotlockAgentOperationDispatchOptions;
     /** Validated W3C trace context to hand the backend (see `SlotlockAgentInvocationContext.trace`). */
     trace?: SlotlockTraceContext;
+    /** The surface the call came through, handed to the backend (`SlotlockAgentInvocationContext.origin`). */
+    origin?: SlotlockChangeOrigin;
 }): Promise<SlotlockAgentOperationDispatchResult>;
 /**
  * Read an A2A `google.protobuf.Timestamp` in its JSON form, as `ListTasks.statusTimestampAfter`
@@ -478,6 +515,12 @@ export declare function describeSlotlockAgentWrite(args: {
     input: Record<string, unknown>;
     signal: AbortSignal;
 }): Promise<string>;
+/**
+ * The A2A skill that watches calendars: `SendStreamingMessage` only. Its stream opens with a task
+ * in TASK_STATE_WORKING and carries a status update for each change to a watched resource's
+ * free/busy, from the same feed as MCP resource subscriptions, until the watch's duration is up.
+ */
+export declare const SLOTLOCK_A2A_WATCH_SKILL = "slotlock_watch_resources";
 export declare function createSlotlockAgentServer(options: SlotlockAgentServerOptions): {
     fetch(request: Request): Promise<Response>;
     manifest: Readonly<Record<string, unknown>>;