@firetail/finchly 0.0.0-stage → 0.0.4

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to `@firetail/finchly`. Versions follow semver.
+
+## Unreleased
+
+## 0.0.4 - 2026-11-12
+
+No change to the package. The first release published by the release
+workflow: 0.0.2 and 0.0.3 were tagged but did not reach npm, because the
+workflow published with a placeholder token in place of the trusted
+publisher. Everything listed under them arrives in this release.
+
+## 0.0.3 - 2026-11-12
+
+Tagged but not published to npm.
+
+- Every request to the platform carries three headers: `x-platform-sdk`
+  (the package name), `x-platform-sdk-version` (this release) and
+  `x-platform-api-version` (the platform API version it speaks). A caller
+  cannot replace them. Exported as `SDK_REQUEST_HEADERS`.
+
+## 0.0.2 - 2026-11-12
+
+Tagged but not published to npm.
+
+- An app can register itself: `createServiceClient` takes an `enrolment`
+  (token, manifest, address) in place of a credential, and
+  `enrolmentFrom(config, manifest)` builds one from the platform settings.
+  Registration is what gets an app's instance key accepted.
+- New error codes: `app_pending_approval`, `app_registration_refused`.
+
+## 0.0.1 - 2026-11-11
+
+The first release, published by hand so that the package exists and
+trusted publishing can be set up. Later releases come from the release
+workflow.
+
+- Package skeleton under its final name.
+- `loadConfig`: read and validate the `PLATFORM_*` settings.
+- `loadManifest`, `checkManifest`: load a manifest and check the fields the
+  SDK depends on.
+- `PLATFORM_API_VERSION`, `SUPPORTED_PLATFORM_API_VERSIONS`, `SDK_NAME`,
+  `SDK_VERSION`.
+- `createIdentityVerifier`: verify the `x-platform-identity` token against
+  the gateway's published keys. Rejections are an `IdentityError` with a
+  `reason` from the specification. Tested against the identity token
+  conformance vectors.
+- New dependency: `jose`.
+- `createServiceClient`: call another service through the gateway, as the
+  service itself or for a user. Makes the instance key, registers it with
+  the service credential, and extends it before it expires.
+- `loadConfig` reads `PLATFORM_SERVICE_CREDENTIAL`.
+- New error codes: `service_call_invalid`, `service_key_rejected`.

package/README.md

@@ -1,3 +1,281 @@
-# Temporary Holding Version
+# @firetail/finchly
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Node SDK for the [Finchly](https://github.com/firetail-io/finchly) platform.
+A service or app uses it to register with a Finchly deployment, verify who
+is calling it, and reach the platform's database, object store, queue and
+other services.
+
+Status: early. The package builds and is tested, but only the first four
+modules exist.
+
+The SDK implements the platform API, which is specified in
+`firetail-io/finchly` under `spec/`. This release speaks platform API `v1`
+(draft).
+
+## Install
+
+```
+npm install @firetail/finchly
+```
+
+Requires Node 22 or later. ESM only.
+
+## Use
+
+```js
+import { loadConfig, loadManifest } from "@firetail/finchly";
+
+const config = loadConfig();                       // reads PLATFORM_* settings
+const manifest = await loadManifest(config.manifestPath);
+```
+
+Both throw a `FinchlyError` with a stable `code` and a `problems` list that
+names everything wrong, so a misconfigured container fails once with the
+full picture.
+
+### Who is calling
+
+The gateway puts a short-lived signed token in the `x-platform-identity`
+header of every request it proxies. It is the only identity a service
+should accept.
+
+```js
+import { IdentityError, createIdentityVerifier } from "@firetail/finchly";
+
+// Once, at startup. It caches the gateway's issuer and signing keys.
+const identity = createIdentityVerifier({
+  slug: manifest.slug,
+  gatewayUrl: config.gatewayUrl,
+});
+
+// Per request.
+try {
+  const caller = await identity.fromHeaders(req.headers);
+  caller.subject;   // user id, or "service:<slug>"
+  caller.email;     // null for a service calling as itself
+  caller.groups;    // platform groups
+  caller.roles;     // roles for this service: "user", "operator"
+  caller.actor;     // "service:<slug>" when a service acts for the user
+} catch (err) {
+  if (err instanceof IdentityError) {
+    // Unauthenticated: respond 401. err.reason is for logs only.
+  } else {
+    // The gateway could not be reached: respond 503.
+    throw err;
+  }
+}
+```
+
+A token is rejected unless it is signed with ES256 by a key the gateway
+publishes, names that gateway as issuer and this service as its only
+audience, and has not expired. The rules are in `spec/identity-token.md` in
+`firetail-io/finchly`.
+
+No other header is ever consulted. On a path the manifest declares in
+`publicPaths` there is no token, and the service authenticates the request
+itself.
+
+### Calling another service
+
+Services never address each other directly. A call goes through the
+gateway, signed by this instance's own key.
+
+```js
+import { createServiceClient } from "@firetail/finchly";
+
+// Once, at startup.
+const service = createServiceClient({
+  slug: manifest.slug,
+  gatewayUrl: config.gatewayUrl,
+  credential: config.serviceCredential,
+});
+await service.start();   // optional: fail now, not on the first call
+
+// As the service itself.
+const res = await service.call("notification-service", "/api/send", {
+  method: "POST",
+  headers: { "content-type": "application/json" },
+  body: JSON.stringify({ text: "hello" }),
+});
+
+// For a user: the target sees that user, and this service acting for them.
+await service.call("notification-service", "/api/inbox", { asUser: caller.subject });
+```
+
+`call` takes the same options as `fetch` and resolves with the response,
+whatever its status.
+
+- **403** means this service's manifest does not list the target in
+  `calls`, or the user has no access to the target.
+- **A redirect is handed back, not followed.**
+- **Nothing is retried.** After a 401 the next call registers the key
+  again, in case the gateway no longer knows it.
+
+The instance makes an ES256 key pair in memory the first time it is needed.
+The private half never leaves the process. The public half is registered
+with the gateway using the credential the service was deployed with, and
+extended by itself for as long as the instance runs. The rules are in
+`spec/service-token.md` and `spec/registration.md` in `firetail-io/finchly`.
+
+### An app registers itself
+
+A built-in service has a credential. An app does not: it registers itself
+with the platform, and that is what gets its key accepted. Give the client
+an `enrolment` in place of a `credential`:
+
+```js
+import { createServiceClient, enrolmentFrom, loadConfig, loadManifest } from "@firetail/finchly";
+
+const config = loadConfig();
+const manifest = await loadManifest(config.manifestPath);
+
+const service = createServiceClient({
+  slug: manifest.slug,
+  gatewayUrl: config.gatewayUrl,
+  credential: config.serviceCredential,          // a built-in service
+  enrolment: enrolmentFrom(config, manifest),    // an app
+});
+await service.start();
+```
+
+`enrolmentFrom` reads the enrolment token (`PLATFORM_ENROLMENT_TOKEN`) and
+the app's address (`PLATFORM_APP_ADDRESS`, or this machine's hostname and
+the manifest's port). It returns `undefined` when there is no token, so the
+same code serves a built-in service and an app.
+
+Registration is the first call the client makes, and it sends the manifest
+exactly as it was loaded. What can come back:
+
+| Error code | Meaning | What to do |
+|---|---|---|
+| none | Registered. Calls work | |
+| `app_pending_approval` | The release waits for an administrator: it asks for more than the last one, or the app is at an address the deployment does not expect | Keep running and try again. The client does not ask the platform again before it was told to |
+| `app_registration_refused` | The platform refused, and `problems` says why: a bad token, a manifest or address it will not accept, a lower version than the one running | Fix the deployment. Trying again will not help |
+| `gateway_unreachable` | The gateway could not be reached | Try again |
+
+The protocol is in `spec/registration.md` in `firetail-io/finchly`.
+
+The other half of the `app` module is not built: serving the
+`/{slug}/_platform/*` endpoints, which let an administrator register an app
+that is already running, and fetching the settings the platform creates for
+an app.
+
+### What every request carries
+
+Every request this SDK makes to the platform says which SDK and which
+release is asking:
+
+| Header | Value |
+|---|---|
+| `x-platform-sdk` | `@firetail/finchly` |
+| `x-platform-sdk-version` | This release, for example `0.0.4` |
+| `x-platform-api-version` | The platform API version it speaks, `v1` |
+
+That covers fetching the gateway's issuer and keys, registering an instance
+key, registering an app, and every call to another service. On a call the
+headers reach the target service too, and a caller cannot replace them.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `PLATFORM_GATEWAY_URL` | yes | The gateway's internal address |
+| `PLATFORM_MANIFEST_PATH` | no | Manifest path in the container. Default `/finchly/manifest.json` |
+| `PLATFORM_APP_ADDRESS` | no | Address the gateway should use to reach this service |
+| `PLATFORM_ENROLMENT_TOKEN` | no | Token for self-registration |
+| `PLATFORM_SERVICE_CREDENTIAL` | no | What a built-in service registers its instance key with |
+
+The enrolment token and the service credential are kept off the enumerable
+properties of the config object, so logging or serialising the config does
+not leak them.
+
+## Modules
+
+| Module | What it does | State |
+|---|---|---|
+| `config` | Read and validate the platform settings | Done |
+| `manifest` | Load the manifest and check what the SDK depends on | Done |
+| `identity` | Verify `x-platform-identity` | Done. Directory lookups (`listUsers`, `membersOf`) and `require*` helpers are planned |
+| `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 | Planned |
+| `blobs` | Object storage with conditional writes | Planned |
+| `queue` | Publish, lease, ack, nack | Planned |
+| `secrets` | Secrets and envelope encryption | Planned |
+| `llm` | Model calls through the platform | Planned |
+| `audit`, `usage`, `notify`, `schedule`, `connectors` | Clients for platform services | Planned |
+| `ui` | Shared header, footer and theme | Planned |
+
+The manifest check here is not the full schema. The platform runs the full
+check at registration and is the authority.
+
+## Develop
+
+```
+npm install
+npm test
+```
+
+`npm test` compiles with `tsc` and runs the tests in `test/` against the
+build, which is what a consumer imports.
+
+### Conformance vectors
+
+`test/conformance/` holds test vectors copied from `firetail-io/finchly`
+(`conformance/vectors/`). Both SDKs must reach the verdict each vector
+states. Do not edit them here: change them in `finchly`, regenerate, and
+copy the file to both SDK repositories. Until `finchly` publishes its
+conformance suite as an image, the copy is made by hand.
+
+## Release
+
+Each package version is semver, independent of the Python SDK and of the
+platform.
+
+1. Changes land on `main` by pull request. Each one adds a line to
+   `CHANGELOG.md` under "Unreleased".
+2. To release, set the version in `package.json`, move the changelog
+   entries under that version, merge, and tag the merge commit `vX.Y.Z`.
+3. The `release` workflow checks the tag matches `package.json`, runs the
+   tests, and publishes.
+4. A version with a pre-release part (`1.2.0-rc.1`) is published under the
+   `next` dist-tag. Anything else is published as `latest`.
+5. A bad release is deprecated with `npm deprecate` and followed by a patch
+   release. It is not unpublished.
+
+Publishing is meant to use npm trusted publishing: the workflow proves its
+identity to npm with its GitHub Actions token, so no npm token is stored,
+and npm attaches a provenance attestation.
+
+npm matches the trusted publisher against the identity GitHub issues to the
+workflow, and every field must match exactly, including case:
+
+| Field on npmjs.com   | Value         |
+| -------------------- | ------------- |
+| Organization or user | `FireTail-io` |
+| Repository           | `finchly-sdk-js` |
+| Workflow filename    | `release.yml` |
+| Environment name     | `npm`         |
+
+The organisation is `FireTail-io`, not `firetail-io`. GitHub accepts either
+spelling in a URL; npm does not, and answers "package not found" when the
+two differ. `repository.url` in `package.json` must use the same spelling.
+The workflow prints the identity it was issued, so a refusal can be compared
+with what npmjs.com holds. A trusted publisher's fields cannot be edited: to
+correct one, delete it and create another.
+
+The workflow can also be given a token, for a release that trusted
+publishing refuses:
+
+- `NPM_TOKEN`, a secret of the `npm` environment in this repository. It is
+  a granular access token that can publish `@firetail/finchly` and nothing
+  else, with a short expiry.
+- npm tries the trusted publisher first and uses the token only when that
+  is refused. Without the secret, nothing in the workflow needs to change.
+- While a token is in use, the package's "Publishing access" on npmjs.com
+  must allow a granular access token with bypass 2FA.
+- No provenance attestation is attached to a release published with the
+  token. npm also does not generate one from a private repository.
+
+Still to add: the conformance suite from `firetail-io/finchly`, run in CI on
+every change, once that suite exists.

package/dist/config.d.ts

@@ -0,0 +1,30 @@
+/** Where the manifest lives in an image unless PLATFORM_MANIFEST_PATH says otherwise. */
+export declare const DEFAULT_MANIFEST_PATH = "/finchly/manifest.json";
+/** Settings a service is deployed with. See spec/registration.md, section 1. */
+export interface PlatformConfig {
+    /** The gateway's internal address, without a trailing slash. */
+    readonly gatewayUrl: string;
+    /** Path of the manifest inside the container. */
+    readonly manifestPath: string;
+    /** Address the gateway should use to reach this service, if set. */
+    readonly appAddress?: string;
+    /**
+     * Enrolment token for self-registration, if set. Not enumerable, so it
+     * does not appear when the config is logged or serialised.
+     */
+    readonly enrolmentToken?: string;
+    /**
+     * The credential a built-in service registers its instance key with, if
+     * set. Not enumerable, like the enrolment token.
+     */
+    readonly serviceCredential?: string;
+}
+type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * Read the platform settings from the environment.
+ *
+ * Throws a FinchlyError listing every problem, so a misconfigured container
+ * fails once with the full picture.
+ */
+export declare function loadConfig(env?: Env): PlatformConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,68 @@
+import { FinchlyError } from "./errors.js";
+/** Where the manifest lives in an image unless PLATFORM_MANIFEST_PATH says otherwise. */
+export const DEFAULT_MANIFEST_PATH = "/finchly/manifest.json";
+function httpUrl(name, value, problems) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        problems.push(`${name} is not a URL`);
+        return undefined;
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        problems.push(`${name} must be an http or https URL`);
+        return undefined;
+    }
+    if (url.username || url.password) {
+        problems.push(`${name} must not contain credentials`);
+        return undefined;
+    }
+    if (url.search || url.hash) {
+        problems.push(`${name} must not have a query string or fragment`);
+        return undefined;
+    }
+    return url.toString().replace(/\/+$/, "");
+}
+/**
+ * Read the platform settings from the environment.
+ *
+ * Throws a FinchlyError listing every problem, so a misconfigured container
+ * fails once with the full picture.
+ */
+export function loadConfig(env = process.env) {
+    const problems = [];
+    const rawGateway = env.PLATFORM_GATEWAY_URL?.trim();
+    let gatewayUrl;
+    if (!rawGateway) {
+        problems.push("PLATFORM_GATEWAY_URL is not set");
+    }
+    else {
+        gatewayUrl = httpUrl("PLATFORM_GATEWAY_URL", rawGateway, problems);
+    }
+    const rawAddress = env.PLATFORM_APP_ADDRESS?.trim();
+    const appAddress = rawAddress ? httpUrl("PLATFORM_APP_ADDRESS", rawAddress, problems) : undefined;
+    const manifestPath = env.PLATFORM_MANIFEST_PATH?.trim() || DEFAULT_MANIFEST_PATH;
+    if (!manifestPath.startsWith("/")) {
+        problems.push("PLATFORM_MANIFEST_PATH must be an absolute path");
+    }
+    const enrolmentToken = env.PLATFORM_ENROLMENT_TOKEN?.trim() || undefined;
+    const serviceCredential = env.PLATFORM_SERVICE_CREDENTIAL?.trim() || undefined;
+    if (problems.length > 0 || gatewayUrl === undefined) {
+        throw new FinchlyError("config_invalid", "Platform settings are invalid", problems);
+    }
+    const config = {
+        gatewayUrl,
+        manifestPath,
+        ...(appAddress !== undefined ? { appAddress } : {}),
+    };
+    for (const [name, value] of [
+        ["enrolmentToken", enrolmentToken],
+        ["serviceCredential", serviceCredential],
+    ]) {
+        if (value !== undefined) {
+            Object.defineProperty(config, name, { value, enumerable: false });
+        }
+    }
+    return Object.freeze(config);
+}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+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";
+/**
+ * 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
+ * report all of them at once instead of one per restart.
+ */
+export declare class FinchlyError extends Error {
+    readonly code: FinchlyErrorCode;
+    readonly problems: readonly string[];
+    constructor(code: FinchlyErrorCode, message: string, problems?: readonly string[]);
+}
+/** Why an identity token was rejected. Defined in spec/identity-token.md. */
+export type IdentityRejection = "missing" | "malformed" | "algorithm" | "unknown_key" | "signature" | "issuer" | "audience" | "expired" | "claims";
+/**
+ * The request carries no acceptable identity. Treat it as unauthenticated
+ * (HTTP 401). `reason` is for logs; do not show it to the caller.
+ */
+export declare class IdentityError extends FinchlyError {
+    readonly reason: IdentityRejection;
+    constructor(reason: IdentityRejection);
+}

package/dist/errors.js

@@ -0,0 +1,27 @@
+/**
+ * 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
+ * report all of them at once instead of one per restart.
+ */
+export class FinchlyError extends Error {
+    code;
+    problems;
+    constructor(code, message, problems = []) {
+        super(problems.length > 0 ? `${message}: ${problems.join("; ")}` : message);
+        this.name = "FinchlyError";
+        this.code = code;
+        this.problems = Object.freeze([...problems]);
+    }
+}
+/**
+ * The request carries no acceptable identity. Treat it as unauthenticated
+ * (HTTP 401). `reason` is for logs; do not show it to the caller.
+ */
+export class IdentityError extends FinchlyError {
+    reason;
+    constructor(reason) {
+        super("identity_invalid", `Identity token rejected: ${reason}`);
+        this.name = "IdentityError";
+        this.reason = reason;
+    }
+}

package/dist/identity.d.ts

@@ -0,0 +1,58 @@
+import type { JSONWebKeySet, JWTPayload } from "jose";
+/** Header the gateway sets on every request it proxies. */
+export declare const IDENTITY_HEADER = "x-platform-identity";
+/** Who is calling, as asserted by the gateway. */
+export interface Identity {
+    /** The user's platform id, or `service:<slug>` for a service calling as itself. */
+    readonly subject: string;
+    /** True when the caller is a service calling as itself, with no user. */
+    readonly service: boolean;
+    readonly email: string | null;
+    readonly name: string | null;
+    /** Platform group names. */
+    readonly groups: readonly string[];
+    /** The user's roles for this service. */
+    readonly roles: readonly string[];
+    /** How the caller was authenticated. */
+    readonly amr: readonly string[];
+    /** `service:<slug>` when a service is acting on the user's behalf. */
+    readonly actor: string | null;
+    readonly sessionId: string | null;
+    /** Every claim in the token. */
+    readonly claims: Readonly<JWTPayload>;
+}
+export interface IdentityVerifierOptions {
+    /** This service's slug. A token for any other service is rejected. */
+    readonly slug: string;
+    /**
+     * The gateway's internal address (PLATFORM_GATEWAY_URL). The issuer and
+     * signing keys are fetched from it. This is the normal way to configure
+     * the verifier.
+     */
+    readonly gatewayUrl?: string;
+    /** Fixed issuer, used with `jwks` in place of `gatewayUrl`. For tests. */
+    readonly issuer?: string;
+    /** Fixed key set, used with `issuer` in place of `gatewayUrl`. For tests. */
+    readonly jwks?: JSONWebKeySet;
+    /** Allowed clock difference with the gateway. Default 30. */
+    readonly clockSkewSeconds?: number;
+    /** Clock, for tests. */
+    readonly now?: () => Date;
+}
+type HeaderBag = {
+    get(name: string): string | null;
+} | Readonly<Record<string, string | readonly string[] | undefined>>;
+export interface IdentityVerifier {
+    /** Verify a token. Throws IdentityError if it is not acceptable. */
+    verify(token: string | null | undefined): Promise<Identity>;
+    /** Verify the token in a request's headers (Node or Fetch style). */
+    fromHeaders(headers: HeaderBag): Promise<Identity>;
+}
+/**
+ * Create a verifier for this service.
+ *
+ * Create one at startup and reuse it: it caches the gateway's issuer and
+ * signing keys.
+ */
+export declare function createIdentityVerifier(options: IdentityVerifierOptions): IdentityVerifier;
+export {};