@firetail/finchly 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 0.0.10 - 2026-11-12
+
+- `createBlobs({ service })`: objects kept with the platform for each
+  tenant. `blobs.forTenant(caller.tenantId)` gives `get`, `put`,
+  `putIfAbsent`, `putIfMatch`, `delete` and `list`. The manifest must set
+  `permissions.blobs`.
+- New error codes: `blobs_not_granted`, `blobs_unavailable`.
+- **Needs a platform that serves objects.**
+
+## 0.0.9 - 2026-11-12
+
+- `createSecrets({ service })`: secrets kept with the platform for each
+  tenant. `secrets.forTenant(caller.tenantId)` gives `get`, `set`,
+  `delete` and `list`, and `encrypt` and `decrypt` under the tenant's key.
+  The manifest must set `permissions.secrets`.
+- `createQueue({ service })`: the platform queue.
+  `queue.forTenant(caller.tenantId).publish(topic, bodies)` publishes for
+  a tenant; `queue.lease(topic)` hands out messages of every tenant, each
+  with `tenantId`, `ack()`, `retry()` and `deadLetter()`. The manifest
+  lists the topics in `permissions.queue`.
+- New error codes: `secrets_not_granted`, `secrets_unavailable`,
+  `secrets_cannot_decrypt`, `queue_not_granted`, `queue_unavailable`.
+- **Needs a platform that serves secrets and the queue.**
+
 ## 0.0.8 - 2026-11-12
 
 - **Breaking:** the database is per tenant. `connectDatabase` no longer

package/README.md

@@ -234,6 +234,143 @@ To run a service on its own, without a platform, give the URL directly:
 `connectDatabase({ url, slug })`. Each tenant's schema is then made the
 first time it is used.
 
+### Secrets
+
+A service whose manifest sets `permissions.secrets` keeps secrets with the
+platform, separately for each tenant:
+
+```js
+import { createSecrets } from "@firetail/finchly";
+
+const secrets = createSecrets({ service });
+
+// Per request: the secrets of the caller's tenant.
+const mine = secrets.forTenant(caller.tenantId);
+
+await mine.set("slack.token", token);
+const value = await mine.get("slack.token"); // undefined if there is none
+await mine.list(); // ["slack.token"]
+await mine.delete("slack.token"); // true if there was one
+```
+
+- A name is 1 to 100 letters, digits, dots, dashes or underscores. A value
+  is text of at most 64 KiB. Do not log a value.
+- A tenant's secrets are read with that tenant's id and no other. Take the
+  id from a verified identity, never from the request itself.
+
+For values the service keeps in its own tables, the platform encrypts and
+decrypts under the tenant's key:
+
+```js
+const sealed = await mine.encrypt(cardNumber, `card:${id}`);
+const opened = await mine.decrypt(sealed, `card:${id}`); // a Uint8Array
+```
+
+The context says what the value is. The same context must be given to
+decrypt, so a value copied to another row does not open there. What was
+encrypted for another tenant, another service or another context, or has
+been changed, rejects with `secrets_cannot_decrypt`.
+
+A manifest that does not ask for secrets gets `secrets_not_granted`. Any
+other refusal is `secrets_unavailable`.
+
+### Objects
+
+A service whose manifest sets `permissions.blobs` keeps objects with the
+platform, separately for each tenant: receipts, exports, files. The service
+holds no credentials for the object store; the platform does.
+
+```js
+import { createBlobs } from "@firetail/finchly";
+
+const blobs = createBlobs({ service });
+
+// Per request: the objects of the caller's tenant.
+const mine = blobs.forTenant(caller.tenantId);
+
+await mine.put(`receipts/${id}.pdf`, bytes, { contentType: "application/pdf" });
+const receipt = await mine.get(`receipts/${id}.pdf`); // undefined if there is none
+receipt.data; // a Uint8Array
+receipt.contentType; // "application/pdf"
+
+const { objects, next } = await mine.list({ prefix: "receipts/", limit: 100 });
+await mine.delete(`receipts/${id}.pdf`);
+```
+
+- A key is 1 to 512 letters, digits, dots, dashes and underscores, in
+  segments divided by `/`. Do not use a key that is also the start of
+  another followed by `/`, such as `a` and `a/b`.
+- An object is text or bytes, of at most 16 MiB.
+- A tenant's objects are reached with that tenant's id and no other. Take
+  the id from a verified identity, never from the request itself.
+- A listing is in key order. When `next` is not undefined there are more:
+  ask again with `{ after: next }`.
+
+Two writers do not lose each other's work if each writes on a condition:
+
+```js
+// Only if there is none by that key. Undefined if there was.
+const made = await mine.putIfAbsent("state.json", "{}", { contentType: "application/json" });
+
+// Only if it has not changed since it was read. Undefined if it has:
+// read again and decide again.
+const state = await mine.get("state.json");
+const next = change(JSON.parse(Buffer.from(state.data).toString()));
+const written = await mine.putIfMatch("state.json", JSON.stringify(next), state.etag, { contentType: "application/json" });
+```
+
+State that needs transactions or queries belongs in the service's
+database, not in an object.
+
+A manifest that does not ask for objects gets `blobs_not_granted`. Any
+other refusal, a deployment with no object store among them, is
+`blobs_unavailable`.
+
+### The queue
+
+A message belongs to a tenant. The manifest lists the topics the service
+publishes to and consumes, in `permissions.queue.publish` and
+`permissions.queue.consume`.
+
+```js
+import { createQueue } from "@firetail/finchly";
+
+const queue = createQueue({ service });
+
+// Per request: publish for the caller's tenant.
+await queue.forTenant(caller.tenantId).publish("notifications", [{ to: caller.subject, text: "Done" }]);
+
+// A worker: take messages of every tenant, and handle each in its own.
+for (const message of await queue.lease("notifications", { max: 10, visibilitySeconds: 60 })) {
+  const db = database.forTenant(message.tenantId);
+  try {
+    await deliver(db, message.body);
+    await message.ack();
+  } catch {
+    await message.retry();
+  }
+}
+```
+
+- **Publishing** takes 1 to 100 bodies, each any JSON value of at most
+  256 KiB, and resolves with their ids. All are published or none.
+  `{ delaySeconds }` holds them back, up to 7 days.
+- **Leasing** hands out messages for `visibilitySeconds` (default 60). A
+  message not answered for in that time is handed out again. An empty list
+  means there is nothing to do; ask again later. `{ tenantId }` takes one
+  tenant's messages only.
+- **Each message says which tenant it is for.** Handle it in that tenant.
+- **Answer for every message**: `ack()` when it is handled, `retry()` to
+  have it handed out again after a wait that doubles each time (or
+  `retry({ delaySeconds })`), `deadLetter(reason)` when it never will be
+  handled. Each resolves with `false` if the time ran out and the message
+  went to another consumer. A message handed out five times without being
+  handled is set aside.
+- A message may be handed out more than once, so handling one twice must be
+  harmless.
+- A topic the manifest does not list rejects with `queue_not_granted`. Any
+  other refusal is `queue_unavailable`.
+
 ### What every request carries
 
 Every request this SDK makes to the platform says which SDK and which
@@ -273,9 +410,9 @@ not leak them.
 | `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Self-registration and key renewal are done, through `service`. Serving `/_platform/*` and fetching settings are not |
 | `service` | Call other services through the gateway, as the service or for a user | Done, for built-in services and for apps |
 | `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Done |
-| `blobs` | Object storage with conditional writes | Planned |
-| `queue` | Publish, lease, ack, nack | Planned |
-| `secrets` | Secrets and envelope encryption | Planned |
+| `blobs` | Objects, with conditional writes | Done. Objects over 16 MiB are not |
+| `queue` | Publish, lease, ack, retry, dead-letter | Done |
+| `secrets` | Secrets, and encryption under the tenant's key | Done |
 | `llm` | Model calls through the platform | Planned |
 | `audit`, `usage`, `notify`, `schedule`, `connectors` | Clients for platform services | Planned |
 | `ui` | Shared header, footer and theme | Planned |

package/dist/blobs.d.ts

@@ -0,0 +1,71 @@
+import type { ServiceClient } from "./service.js";
+/** An object, as it was read. */
+export interface StoredBlob {
+    readonly data: Uint8Array;
+    /** Changes whenever the content does. Hand it to `putIfMatch` as it came. */
+    readonly etag: string;
+    readonly contentType: string;
+}
+/** What a listing says of an object. */
+export interface BlobInfo {
+    readonly key: string;
+    /** In bytes. */
+    readonly size: number;
+    readonly etag: string;
+    readonly modifiedAt: Date;
+}
+export interface PutOptions {
+    /** Kept with the object. Default: text/plain for text, application/octet-stream for bytes. */
+    readonly contentType?: string;
+}
+export interface ListOptions {
+    /** The start of the keys to list. May end anywhere. Default: every key. */
+    readonly prefix?: string;
+    /** List the keys after this one: the `next` of the page before. */
+    readonly after?: string;
+    /** The most objects to list. 1 to 1000, default 100. */
+    readonly limit?: number;
+}
+export interface BlobPage {
+    /** In key order. */
+    readonly objects: BlobInfo[];
+    /** Pass as `after` for the next page. Undefined when there are no more. */
+    readonly next: string | undefined;
+}
+/** A service's objects in one tenant. */
+export interface TenantBlobs {
+    readonly tenantId: string;
+    /** The object, or undefined if there is none by that key. */
+    get(key: string): Promise<StoredBlob | undefined>;
+    /** Write an object, replacing any there was. At most 16 MiB. Resolves with its etag. */
+    put(key: string, data: string | Uint8Array, options?: PutOptions): Promise<string>;
+    /**
+     * Write an object only if there is none by that key. Resolves with its
+     * etag, or undefined if there was one, which is left as it is.
+     */
+    putIfAbsent(key: string, data: string | Uint8Array, options?: PutOptions): Promise<string | undefined>;
+    /**
+     * Write an object only if it still has the etag it was read with.
+     * Resolves with the new etag, or undefined if it has changed or gone:
+     * read it again and decide again. This is how two writers do not lose
+     * each other's work.
+     */
+    putIfMatch(key: string, data: string | Uint8Array, etag: string, options?: PutOptions): Promise<string | undefined>;
+    /** Delete an object. Not an error if there is none. */
+    delete(key: string): Promise<void>;
+    /** The service's objects in this tenant, a page at a time. */
+    list(options?: ListOptions): Promise<BlobPage>;
+}
+export interface Blobs {
+    /**
+     * The objects of one tenant: `caller.tenantId` of the request being
+     * handled. Take the id from a verified identity, never from the request
+     * itself.
+     */
+    forTenant(tenantId: string): TenantBlobs;
+}
+export interface BlobsOptions {
+    /** The service's client. Every call goes through it. */
+    readonly service: Pick<ServiceClient, "call">;
+}
+export declare function createBlobs(options: BlobsOptions): Blobs;

package/dist/blobs.js

@@ -0,0 +1,134 @@
+// Objects a service keeps with the platform, for each tenant. See
+// spec/blobs.md in the platform repository.
+//
+// The manifest must set permissions.blobs. Everything here is for one
+// tenant: the handle that reads and writes is made with `forTenant`. The
+// service holds no credentials for the object store; the platform does.
+import { FinchlyError } from "./errors.js";
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
+const KEY = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
+const PREFIX = /^[A-Za-z0-9._/-]*$/;
+const MAX_KEY_LENGTH = 512;
+/** The largest object the platform takes. */
+const MAX_BYTES = 16 * 1024 * 1024;
+const BASE = "/api/apps/self/blobs";
+const unavailable = (message) => new FinchlyError("blobs_unavailable", message);
+function isKey(key) {
+    return typeof key === "string" && key.length <= MAX_KEY_LENGTH && KEY.test(key) && !key.split("/").some((segment) => segment === "." || segment === "..");
+}
+function checkKey(key) {
+    if (!isKey(key)) {
+        throw unavailable('A key is 1 to 512 letters, digits, dots, dashes and underscores, in segments divided by "/"');
+    }
+}
+async function failure(response, what) {
+    const answer = (await response.json().catch(() => null));
+    const error = typeof answer?.error === "string" ? answer.error : undefined;
+    if (error === "not_granted") {
+        return new FinchlyError("blobs_not_granted", "The platform keeps no objects for this service", [
+            "Set permissions.blobs to true in the manifest",
+        ]);
+    }
+    return new FinchlyError("blobs_unavailable", `The platform did not ${what}`, [
+        `it answered ${response.status}${error ? ` ${error}` : ""}${typeof answer?.detail === "string" ? `: ${answer.detail}` : ""}`,
+    ]);
+}
+export function createBlobs(options) {
+    const { service } = options;
+    return {
+        forTenant(tenantId) {
+            if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
+                throw unavailable("forTenant needs a tenant id, as in caller.tenantId");
+            }
+            /** Write, with a condition or none. Undefined if the condition did not hold. */
+            async function write(key, data, condition, putOptions = {}) {
+                checkKey(key);
+                const text = typeof data === "string";
+                if (!text && !(data instanceof Uint8Array))
+                    throw unavailable("An object is text or bytes");
+                const bytes = text ? Buffer.from(data, "utf8") : data;
+                if (bytes.byteLength > MAX_BYTES)
+                    throw unavailable("An object is at most 16 MiB");
+                const contentType = putOptions.contentType ?? (text ? "text/plain; charset=utf-8" : "application/octet-stream");
+                if (typeof contentType !== "string" || !/^[\x20-\x7e]{1,200}$/.test(contentType))
+                    throw unavailable("The content type is not one");
+                const response = await service.call("core", `${BASE}/${key}`, {
+                    tenantId,
+                    method: "PUT",
+                    headers: { "content-type": contentType, ...condition },
+                    body: bytes,
+                });
+                if (response.status === 412) {
+                    await response.body?.cancel();
+                    return undefined;
+                }
+                if (response.status !== 200)
+                    throw await failure(response, "keep the object");
+                return (await response.json()).etag;
+            }
+            return {
+                tenantId,
+                async get(key) {
+                    checkKey(key);
+                    const response = await service.call("core", `${BASE}/${key}`, { tenantId });
+                    if (response.status === 404) {
+                        await response.body?.cancel();
+                        return undefined;
+                    }
+                    if (response.status !== 200)
+                        throw await failure(response, "give the object");
+                    return {
+                        data: new Uint8Array(await response.arrayBuffer()),
+                        etag: response.headers.get("etag") ?? "",
+                        contentType: response.headers.get("content-type") ?? "application/octet-stream",
+                    };
+                },
+                async put(key, data, putOptions) {
+                    // With no condition there is nothing not to hold.
+                    return (await write(key, data, {}, putOptions));
+                },
+                putIfAbsent(key, data, putOptions) {
+                    return write(key, data, { "if-none-match": "*" }, putOptions);
+                },
+                async putIfMatch(key, data, etag, putOptions) {
+                    if (typeof etag !== "string" || etag === "" || etag.length > 200) {
+                        throw unavailable("putIfMatch needs the etag the object was read with");
+                    }
+                    return write(key, data, { "if-match": etag }, putOptions);
+                },
+                async delete(key) {
+                    checkKey(key);
+                    const response = await service.call("core", `${BASE}/${key}`, { tenantId, method: "DELETE" });
+                    if (response.status !== 204)
+                        throw await failure(response, "delete the object");
+                },
+                async list(listOptions = {}) {
+                    const { prefix, after, limit } = listOptions;
+                    if (prefix !== undefined && (typeof prefix !== "string" || prefix.length > MAX_KEY_LENGTH || !PREFIX.test(prefix))) {
+                        throw unavailable("A prefix is the start of a key");
+                    }
+                    if (after !== undefined)
+                        checkKey(after);
+                    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1 || limit > 1000)) {
+                        throw unavailable("limit is 1 to 1000");
+                    }
+                    const query = new URLSearchParams();
+                    if (prefix)
+                        query.set("prefix", prefix);
+                    if (after !== undefined)
+                        query.set("after", after);
+                    if (limit !== undefined)
+                        query.set("limit", String(limit));
+                    const response = await service.call("core", query.size > 0 ? `${BASE}?${query}` : BASE, { tenantId });
+                    if (response.status !== 200)
+                        throw await failure(response, "list the objects");
+                    const page = (await response.json());
+                    return {
+                        objects: page.objects.map(({ key, size, etag, modifiedAt }) => ({ key, size, etag, modifiedAt: new Date(modifiedAt) })),
+                        next: page.next ?? undefined,
+                    };
+                },
+            };
+        },
+    };
+}

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type FinchlyErrorCode = "config_invalid" | "manifest_invalid" | "manifest_unreadable" | "identity_invalid" | "gateway_unreachable" | "platform_api_unsupported" | "service_call_invalid" | "service_key_rejected" | "app_registration_refused" | "app_pending_approval" | "database_unavailable" | "database_not_granted" | "migration_invalid";
+export type FinchlyErrorCode = "config_invalid" | "manifest_invalid" | "manifest_unreadable" | "identity_invalid" | "gateway_unreachable" | "platform_api_unsupported" | "service_call_invalid" | "service_key_rejected" | "app_registration_refused" | "app_pending_approval" | "database_unavailable" | "database_not_granted" | "migration_invalid" | "secrets_not_granted" | "secrets_unavailable" | "secrets_cannot_decrypt" | "queue_not_granted" | "queue_unavailable" | "blobs_not_granted" | "blobs_unavailable";
 /**
  * Every error this SDK throws on purpose. `code` is stable and safe to
  * branch on; `problems` lists each thing that was wrong, so a caller can

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export { createBlobs } from "./blobs.js";
+export type { BlobInfo, BlobPage, Blobs, BlobsOptions, ListOptions, PutOptions, StoredBlob, TenantBlobs } from "./blobs.js";
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
 export type { PlatformConfig } from "./config.js";
 export { connectDatabase, fetchSettings } from "./db.js";
@@ -10,6 +12,10 @@ export { checkManifest, loadManifest } from "./manifest.js";
 export type { Manifest, ManifestPermissions, PublicPath } from "./manifest.js";
 export { MANIFEST_VERSION, PLATFORM_API_VERSION, SUPPORTED_PLATFORM_API_VERSIONS, } from "./platform-api.js";
 export { PLATFORM_API_VERSION_HEADER, SDK_HEADER, SDK_REQUEST_HEADERS, SDK_VERSION_HEADER, } from "./request-headers.js";
+export { createQueue } from "./queue.js";
+export type { LeaseOptions, Message, PublishOptions, Queue, QueueOptions, TenantQueue } from "./queue.js";
+export { createSecrets } from "./secrets.js";
+export type { Secrets, SecretsOptions, TenantSecrets } from "./secrets.js";
 export { createServiceClient, enrolmentFrom } from "./service.js";
 export type { CallOptions, Enrolment, ServiceClient, ServiceClientOptions } from "./service.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/index.js

@@ -1,3 +1,4 @@
+export { createBlobs } from "./blobs.js";
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
 export { connectDatabase, fetchSettings } from "./db.js";
 export { FinchlyError, IdentityError } from "./errors.js";
@@ -5,5 +6,7 @@ export { IDENTITY_HEADER, createIdentityVerifier } from "./identity.js";
 export { checkManifest, loadManifest } from "./manifest.js";
 export { MANIFEST_VERSION, PLATFORM_API_VERSION, SUPPORTED_PLATFORM_API_VERSIONS, } from "./platform-api.js";
 export { PLATFORM_API_VERSION_HEADER, SDK_HEADER, SDK_REQUEST_HEADERS, SDK_VERSION_HEADER, } from "./request-headers.js";
+export { createQueue } from "./queue.js";
+export { createSecrets } from "./secrets.js";
 export { createServiceClient, enrolmentFrom } from "./service.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/queue.d.ts

@@ -0,0 +1,70 @@
+import type { ServiceClient } from "./service.js";
+export interface PublishOptions {
+    /** Not handed out before this many seconds have passed. Up to 7 days. */
+    readonly delaySeconds?: number;
+}
+/** The queue, for one tenant: where messages are published. */
+export interface TenantQueue {
+    readonly tenantId: string;
+    /**
+     * Publish messages to a topic, for this tenant. Each body is any JSON
+     * value of at most 256 KiB; 1 to 100 at a time. Resolves with their ids.
+     * All of them are published, or none.
+     */
+    publish(topic: string, bodies: readonly unknown[], options?: PublishOptions): Promise<string[]>;
+}
+/** A message that was handed out. Answer for it with `ack`, `retry` or `deadLetter`. */
+export interface Message {
+    readonly id: string;
+    /** The tenant the message is for. Handle it in that tenant, and no other. */
+    readonly tenantId: string;
+    readonly body: unknown;
+    /** How many times it has been handed out, this time included. */
+    readonly attempts: number;
+    /** The service that published it. */
+    readonly publishedBy: string;
+    readonly publishedAt: Date;
+    /**
+     * It was handled: delete it. Resolves with false if this consumer no
+     * longer holds it, because the time ran out and it was handed to another.
+     */
+    ack(): Promise<boolean>;
+    /**
+     * It was not handled: have it handed out again, after `delaySeconds`, or
+     * after a wait that doubles each time if that is left out.
+     */
+    retry(options?: {
+        readonly delaySeconds?: number;
+    }): Promise<boolean>;
+    /** It never will be handled: set it aside. It is kept, and not handed out again. */
+    deadLetter(reason?: string): Promise<boolean>;
+}
+export interface LeaseOptions {
+    /** The most messages to take. 1 to 100, default 10. */
+    readonly max?: number;
+    /**
+     * How long this consumer has to answer before a message is handed to
+     * another. 1 second to 12 hours, default 60 seconds.
+     */
+    readonly visibilitySeconds?: number;
+    /** Take one tenant's messages only. Default: every tenant that uses this service. */
+    readonly tenantId?: string;
+}
+export interface Queue {
+    /**
+     * The queue for one tenant, to publish to: `caller.tenantId` of the
+     * request being handled. Take the id from a verified identity, never from
+     * the request itself.
+     */
+    forTenant(tenantId: string): TenantQueue;
+    /**
+     * Take messages from a topic. Each comes with the tenant it is for. An
+     * empty list means there is nothing to do; ask again later.
+     */
+    lease(topic: string, options?: LeaseOptions): Promise<Message[]>;
+}
+export interface QueueOptions {
+    /** The service's client. Every call goes through it. */
+    readonly service: Pick<ServiceClient, "call">;
+}
+export declare function createQueue(options: QueueOptions): Queue;

package/dist/queue.js

@@ -0,0 +1,95 @@
+// The platform queue. See spec/queue.md in the platform repository.
+//
+// A message belongs to a tenant. Publishing is done for one tenant, on a
+// handle made with `forTenant`. Consuming is the service's own work: one
+// running copy serves every tenant, so `lease` hands out messages of every
+// tenant that uses the service, each with the tenant it is for.
+//
+// The manifest lists what may be published and consumed, in
+// permissions.queue.
+import { FinchlyError } from "./errors.js";
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
+const TOPIC = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const BASE = "/api/apps/self/queue";
+async function failure(response, what, topic) {
+    const answer = (await response.json().catch(() => null));
+    const error = typeof answer?.error === "string" ? answer.error : undefined;
+    if (error === "not_granted") {
+        return new FinchlyError("queue_not_granted", `This service may not ${what}${topic ? ` ${topic}` : ""}`, [
+            `List the topic in permissions.queue.${what === "publish to" ? "publish" : "consume"} in the manifest`,
+        ]);
+    }
+    return new FinchlyError("queue_unavailable", `The platform queue did not ${what === "publish to" ? "take the messages" : "answer"}`, [
+        `it answered ${response.status}${error ? ` ${error}` : ""}${typeof answer?.detail === "string" ? `: ${answer.detail}` : ""}`,
+    ]);
+}
+function checkTopic(topic) {
+    if (typeof topic !== "string" || topic.length < 2 || topic.length > 60 || !TOPIC.test(topic)) {
+        throw new FinchlyError("queue_unavailable", "A topic is 2 to 60 lower-case letters, digits and dashes");
+    }
+}
+function checkTenant(tenantId, where) {
+    if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
+        throw new FinchlyError("queue_unavailable", `${where} needs a tenant id, as in caller.tenantId`);
+    }
+}
+export function createQueue(options) {
+    const { service } = options;
+    const post = (path, body, tenantId) => service.call("core", `${BASE}${path}`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        ...(tenantId !== undefined ? { tenantId } : {}),
+    });
+    /** Answer for a message that was handed out. False if this consumer no longer holds it. */
+    async function answer(action, held, extra) {
+        const response = await post(`/${action}`, { ...held, ...extra });
+        if (response.status === 409) {
+            await response.body?.cancel();
+            return false;
+        }
+        if (response.status !== 204)
+            throw await failure(response, "consume");
+        return true;
+    }
+    return {
+        forTenant(tenantId) {
+            checkTenant(tenantId, "forTenant");
+            return {
+                tenantId,
+                async publish(topic, bodies, publishOptions = {}) {
+                    checkTopic(topic);
+                    if (!Array.isArray(bodies) || bodies.length === 0) {
+                        throw new FinchlyError("queue_unavailable", "publish takes a list of at least one message body");
+                    }
+                    const { delaySeconds } = publishOptions;
+                    const messages = bodies.map((body) => ({ body: body === undefined ? null : body, ...(delaySeconds !== undefined ? { delaySeconds } : {}) }));
+                    const response = await post(`/${topic}/messages`, { messages }, tenantId);
+                    if (response.status !== 201)
+                        throw await failure(response, "publish to", topic);
+                    return (await response.json()).ids;
+                },
+            };
+        },
+        async lease(topic, leaseOptions = {}) {
+            checkTopic(topic);
+            const { max, visibilitySeconds, tenantId } = leaseOptions;
+            if (tenantId !== undefined)
+                checkTenant(tenantId, "lease");
+            const response = await post(`/${topic}/lease`, { ...(max !== undefined ? { max } : {}), ...(visibilitySeconds !== undefined ? { visibilitySeconds } : {}) }, tenantId);
+            if (response.status !== 200)
+                throw await failure(response, "consume", topic);
+            const { messages } = (await response.json());
+            return messages.map(({ leaseToken, publishedAt, ...message }) => {
+                const held = { tenantId: message.tenantId, id: message.id, leaseToken };
+                return {
+                    ...message,
+                    publishedAt: new Date(publishedAt),
+                    ack: () => answer("ack", held, {}),
+                    retry: (retryOptions = {}) => answer("nack", held, retryOptions.delaySeconds !== undefined ? { delaySeconds: retryOptions.delaySeconds } : {}),
+                    deadLetter: (reason) => answer("dead-letter", held, reason !== undefined ? { reason } : {}),
+                };
+            });
+        },
+    };
+}

package/dist/secrets.d.ts

@@ -0,0 +1,39 @@
+import type { ServiceClient } from "./service.js";
+/** A service's secrets in one tenant. */
+export interface TenantSecrets {
+    readonly tenantId: string;
+    /** A secret's value, or undefined if there is none by that name. Do not log it. */
+    get(name: string): Promise<string | undefined>;
+    /** Keep a secret, replacing any there was. The value is text of at most 64 KiB. */
+    set(name: string, value: string): Promise<void>;
+    /** Forget a secret. Resolves with whether there was one. */
+    delete(name: string): Promise<boolean>;
+    /** The names of the secrets kept. Never the values. */
+    list(): Promise<string[]>;
+    /**
+     * Have the platform encrypt something under the tenant's key, to keep in
+     * the service's own tables. `context` says what the value is, for example
+     * "payments:card:7"; the same context must be given to decrypt, so a
+     * value moved to another row does not open there.
+     */
+    encrypt(plaintext: string | Uint8Array, context?: string): Promise<string>;
+    /**
+     * Open what `encrypt` gave. Rejects with `secrets_cannot_decrypt` if it
+     * was made for another tenant, another service or another context, or
+     * has been changed.
+     */
+    decrypt(ciphertext: string, context?: string): Promise<Uint8Array>;
+}
+export interface Secrets {
+    /**
+     * The secrets of one tenant: `caller.tenantId` of the request being
+     * handled. Take the id from a verified identity, never from the request
+     * itself.
+     */
+    forTenant(tenantId: string): TenantSecrets;
+}
+export interface SecretsOptions {
+    /** The service's client. Every call goes through it. */
+    readonly service: Pick<ServiceClient, "call">;
+}
+export declare function createSecrets(options: SecretsOptions): Secrets;

package/dist/secrets.js

@@ -0,0 +1,97 @@
+// Secrets a service keeps with the platform, for each tenant, and
+// encryption under the tenant's key. See spec/secrets.md in the platform
+// repository.
+//
+// The manifest must set permissions.secrets. Everything here is for one
+// tenant: the handle that reads and writes is made with `forTenant`.
+import { FinchlyError } from "./errors.js";
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
+const NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const BASE = "/api/apps/self";
+async function failure(response, what) {
+    const answer = (await response.json().catch(() => null));
+    const error = typeof answer?.error === "string" ? answer.error : undefined;
+    if (error === "not_granted") {
+        return new FinchlyError("secrets_not_granted", "The platform keeps no secrets for this service", [
+            "Set permissions.secrets to true in the manifest",
+        ]);
+    }
+    return new FinchlyError("secrets_unavailable", `The platform did not ${what}`, [
+        `it answered ${response.status}${error ? ` ${error}` : ""}`,
+    ]);
+}
+export function createSecrets(options) {
+    const { service } = options;
+    return {
+        forTenant(tenantId) {
+            if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
+                throw new FinchlyError("secrets_unavailable", "forTenant needs a tenant id, as in caller.tenantId");
+            }
+            const call = (path, method = "GET", body) => service.call("core", `${BASE}${path}`, {
+                tenantId,
+                method,
+                ...(body !== undefined ? { headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : {}),
+            });
+            const named = (name) => {
+                if (typeof name !== "string" || !NAME.test(name)) {
+                    throw new FinchlyError("secrets_unavailable", "A secret's name is 1 to 100 letters, digits, dots, dashes or underscores");
+                }
+                return `/secrets/${name}`;
+            };
+            return {
+                tenantId,
+                async get(name) {
+                    const response = await call(named(name));
+                    if (response.status === 404) {
+                        await response.body?.cancel();
+                        return undefined;
+                    }
+                    if (response.status !== 200)
+                        throw await failure(response, "give the secret");
+                    return (await response.json()).value;
+                },
+                async set(name, value) {
+                    if (typeof value !== "string")
+                        throw new FinchlyError("secrets_unavailable", "A secret's value is text");
+                    const response = await call(named(name), "PUT", { value });
+                    if (response.status !== 204)
+                        throw await failure(response, "keep the secret");
+                },
+                async delete(name) {
+                    const response = await call(named(name), "DELETE");
+                    if (response.status === 404) {
+                        await response.body?.cancel();
+                        return false;
+                    }
+                    if (response.status !== 204)
+                        throw await failure(response, "forget the secret");
+                    return true;
+                },
+                async list() {
+                    const response = await call("/secrets");
+                    if (response.status !== 200)
+                        throw await failure(response, "list the secrets");
+                    return (await response.json()).names;
+                },
+                async encrypt(plaintext, context) {
+                    const bytes = typeof plaintext === "string" ? Buffer.from(plaintext, "utf8") : Buffer.from(plaintext);
+                    const response = await call("/encrypt", "POST", { plaintext: bytes.toString("base64"), ...(context !== undefined ? { context } : {}) });
+                    if (response.status !== 200)
+                        throw await failure(response, "encrypt");
+                    return (await response.json()).ciphertext;
+                },
+                async decrypt(ciphertext, context) {
+                    const response = await call("/decrypt", "POST", { ciphertext, ...(context !== undefined ? { context } : {}) });
+                    if (response.status === 400) {
+                        await response.body?.cancel();
+                        // Another tenant's, another service's, another context's, or changed: the platform does not say which.
+                        throw new FinchlyError("secrets_cannot_decrypt", "The platform could not decrypt this");
+                    }
+                    if (response.status !== 200)
+                        throw await failure(response, "decrypt");
+                    return Buffer.from((await response.json()).plaintext, "base64");
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",