@firetail/finchly 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to `@firetail/finchly`. Versions follow semver.
+
+## Unreleased
+
+## 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,208 @@
-# 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`.
+
+Only a built-in service has a credential. An app's key is accepted when it
+registers, which the `app` module will do; until then an app cannot use
+`service`.
+
+### 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 | Next |
+| `service` | Call other services through the gateway, as the service or for a user | Done for built-in services. An app's first key waits on `app` |
+| `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 uses npm trusted publishing: the workflow proves its identity to
+npm with its GitHub Actions token, so no npm token is stored in this
+repository, and npm attaches a provenance attestation.
+
+One-time setup, not yet done:
+
+- On npmjs.com, add this repository and the `release.yml` workflow as a
+  trusted publisher for `@firetail/finchly`, with the `npm` environment.
+- Create a GitHub environment called `npm` in this repository, restricted
+  to tags.
+- npm may require the package to exist before a trusted publisher can be
+  added. If so, the very first publish is done by hand by an owner of the
+  `@firetail` scope, and every release after that goes through the
+  workflow.
+
+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";
+/**
+ * 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 {};

package/dist/identity.js

@@ -0,0 +1,232 @@
+// Verifies the x-platform-identity token. Every check here is required by
+// spec/identity-token.md in firetail-io/finchly, and the conformance vectors
+// in test/conformance pin the verdict for each kind of bad token.
+import { createLocalJWKSet, createRemoteJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
+import { FinchlyError, IdentityError } from "./errors.js";
+import { SUPPORTED_PLATFORM_API_VERSIONS } from "./platform-api.js";
+/** Header the gateway sets on every request it proxies. */
+export const IDENTITY_HEADER = "x-platform-identity";
+const REQUIRED_CLAIMS = ["iss", "sub", "aud", "iat", "exp"];
+const DEFAULT_CLOCK_SKEW_SECONDS = 30;
+const KEY_CACHE_MS = 60 * 60 * 1000;
+const KEY_REFETCH_COOLDOWN_MS = 30 * 1000;
+const GATEWAY_TIMEOUT_MS = 5000;
+const SLUG = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+function stringArray(value) {
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value) && value.every((v) => typeof v === "string")) {
+        return Object.freeze([...value]);
+    }
+    return undefined;
+}
+function optionalString(value) {
+    if (value === undefined)
+        return null;
+    return typeof value === "string" ? value : undefined;
+}
+/** Build the Identity from verified claims, rejecting wrongly typed ones. */
+function toIdentity(payload, slug) {
+    // A token is for exactly one service. A list of audiences that happens to
+    // include this one is not accepted.
+    if (payload.aud !== slug) {
+        throw new IdentityError("audience");
+    }
+    if (typeof payload.sub !== "string" || payload.sub.length === 0) {
+        throw new IdentityError("claims");
+    }
+    if (typeof payload.iat !== "number" || typeof payload.exp !== "number") {
+        throw new IdentityError("claims");
+    }
+    const email = optionalString(payload.email);
+    const name = optionalString(payload.name);
+    const sessionId = optionalString(payload.sid);
+    const groups = stringArray(payload.groups);
+    const roles = stringArray(payload.roles);
+    const amr = stringArray(payload.amr);
+    let actor = null;
+    if (payload.act !== undefined) {
+        const act = payload.act;
+        actor = typeof act === "object" && act !== null && typeof act.sub === "string" ? act.sub : undefined;
+    }
+    if (email === undefined ||
+        name === undefined ||
+        sessionId === undefined ||
+        groups === undefined ||
+        roles === undefined ||
+        amr === undefined ||
+        actor === undefined) {
+        throw new IdentityError("claims");
+    }
+    return Object.freeze({
+        subject: payload.sub,
+        service: payload.sub.startsWith("service:"),
+        email,
+        name,
+        groups,
+        roles,
+        amr,
+        actor,
+        sessionId,
+        claims: Object.freeze({ ...payload }),
+    });
+}
+function rejectionFor(err) {
+    if (err instanceof IdentityError)
+        return err;
+    if (err instanceof errors.JWTExpired)
+        return new IdentityError("expired");
+    if (err instanceof errors.JWTClaimValidationFailed) {
+        if (err.reason === "missing")
+            return new IdentityError("claims");
+        if (err.claim === "iss")
+            return new IdentityError("issuer");
+        if (err.claim === "aud")
+            return new IdentityError("audience");
+        return new IdentityError("claims");
+    }
+    if (err instanceof errors.JWKSNoMatchingKey || err instanceof errors.JWKSMultipleMatchingKeys) {
+        return new IdentityError("unknown_key");
+    }
+    if (err instanceof errors.JWSSignatureVerificationFailed)
+        return new IdentityError("signature");
+    if (err instanceof errors.JOSEAlgNotAllowed)
+        return new IdentityError("algorithm");
+    if (err instanceof errors.JWSInvalid || err instanceof errors.JWTInvalid) {
+        return new IdentityError("malformed");
+    }
+    return undefined;
+}
+/**
+ * Create a verifier for this service.
+ *
+ * Create one at startup and reuse it: it caches the gateway's issuer and
+ * signing keys.
+ */
+export function createIdentityVerifier(options) {
+    const problems = [];
+    if (typeof options.slug !== "string" || !SLUG.test(options.slug)) {
+        problems.push("slug must be this service's slug");
+    }
+    const fixed = options.issuer !== undefined || options.jwks !== undefined;
+    if (fixed && options.gatewayUrl !== undefined) {
+        problems.push("give either gatewayUrl, or issuer and jwks, not both");
+    }
+    else if (fixed && (options.issuer === undefined || options.jwks === undefined)) {
+        problems.push("issuer and jwks must be given together");
+    }
+    else if (!fixed && !options.gatewayUrl) {
+        problems.push("gatewayUrl is required");
+    }
+    const skew = options.clockSkewSeconds ?? DEFAULT_CLOCK_SKEW_SECONDS;
+    if (!Number.isFinite(skew) || skew < 0) {
+        problems.push("clockSkewSeconds must be zero or more");
+    }
+    if (problems.length > 0) {
+        throw new FinchlyError("config_invalid", "Identity verifier options are invalid", problems);
+    }
+    const slug = options.slug;
+    const now = options.now ?? (() => new Date());
+    const gatewayUrl = options.gatewayUrl?.replace(/\/+$/, "");
+    let trust = options.issuer !== undefined && options.jwks !== undefined
+        ? Promise.resolve({ issuer: options.issuer, getKey: createLocalJWKSet(options.jwks) })
+        : undefined;
+    async function discover() {
+        const url = `${gatewayUrl}/_gateway/.well-known/platform.json`;
+        let body;
+        try {
+            const response = await fetch(url, { signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS) });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            body = await response.json();
+        }
+        catch (cause) {
+            const reason = cause instanceof Error ? cause.message : String(cause);
+            throw new FinchlyError("gateway_unreachable", `Cannot read ${url}`, [reason]);
+        }
+        const doc = (typeof body === "object" && body !== null ? body : {});
+        if (typeof doc.issuer !== "string" || doc.issuer.length === 0) {
+            throw new FinchlyError("gateway_unreachable", `${url} does not name an issuer`);
+        }
+        const served = Array.isArray(doc.platformApi) ? doc.platformApi : [];
+        if (!served.some((v) => SUPPORTED_PLATFORM_API_VERSIONS.includes(v))) {
+            throw new FinchlyError("platform_api_unsupported", `The gateway serves platform API ${JSON.stringify(served)}; this SDK speaks ${SUPPORTED_PLATFORM_API_VERSIONS.join(", ")}`);
+        }
+        return {
+            issuer: doc.issuer,
+            getKey: createRemoteJWKSet(new URL(`${gatewayUrl}/_gateway/.well-known/jwks.json`), {
+                cacheMaxAge: KEY_CACHE_MS,
+                cooldownDuration: KEY_REFETCH_COOLDOWN_MS,
+                timeoutDuration: GATEWAY_TIMEOUT_MS,
+            }),
+        };
+    }
+    function getTrust() {
+        if (trust === undefined) {
+            const attempt = discover();
+            trust = attempt;
+            // A failed discovery is not cached: the next request tries again.
+            attempt.catch(() => {
+                if (trust === attempt)
+                    trust = undefined;
+            });
+        }
+        return trust;
+    }
+    async function verify(token) {
+        if (typeof token !== "string" || token.length === 0) {
+            throw new IdentityError("missing");
+        }
+        let alg;
+        try {
+            alg = decodeProtectedHeader(token).alg;
+        }
+        catch {
+            throw new IdentityError("malformed");
+        }
+        // Checked first and by hand, so that no other property of the token can
+        // influence what happens to one with the wrong algorithm.
+        if (alg !== "ES256") {
+            throw new IdentityError("algorithm");
+        }
+        const { issuer, getKey } = await getTrust();
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, getKey, {
+                algorithms: ["ES256"],
+                issuer,
+                audience: slug,
+                clockTolerance: skew,
+                currentDate: now(),
+                requiredClaims: REQUIRED_CLAIMS,
+            }));
+        }
+        catch (err) {
+            const rejection = rejectionFor(err);
+            if (rejection)
+                throw rejection;
+            // Anything else is a failure to fetch the keys, not a bad token. It
+            // must not be reported as the caller's fault.
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new FinchlyError("gateway_unreachable", "Cannot fetch the gateway's signing keys", [reason]);
+        }
+        return toIdentity(payload, slug);
+    }
+    function fromHeaders(headers) {
+        let value;
+        if (typeof headers.get === "function") {
+            value = headers.get(IDENTITY_HEADER);
+        }
+        else {
+            value = headers[IDENTITY_HEADER];
+        }
+        // The gateway sets the header exactly once. More than one value means
+        // something else added one.
+        if (Array.isArray(value)) {
+            return Promise.reject(new IdentityError(value.length === 0 ? "missing" : "malformed"));
+        }
+        return verify(value);
+    }
+    return Object.freeze({ verify, fromHeaders });
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
+export type { PlatformConfig } from "./config.js";
+export { FinchlyError, IdentityError } from "./errors.js";
+export type { FinchlyErrorCode, IdentityRejection } from "./errors.js";
+export { IDENTITY_HEADER, createIdentityVerifier } from "./identity.js";
+export type { Identity, IdentityVerifier, IdentityVerifierOptions } from "./identity.js";
+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 { createServiceClient } from "./service.js";
+export type { CallOptions, ServiceClient, ServiceClientOptions } from "./service.js";
+export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
+export { FinchlyError, IdentityError } from "./errors.js";
+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 { createServiceClient } from "./service.js";
+export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/manifest.d.ts

@@ -0,0 +1,49 @@
+export interface PublicPath {
+    readonly pattern: string;
+    readonly methods?: readonly string[];
+}
+export interface ManifestPermissions {
+    readonly db?: boolean;
+    readonly blobs?: boolean;
+    readonly secrets?: boolean;
+    readonly llm?: boolean;
+    readonly vectors?: boolean;
+    readonly notify?: boolean;
+    readonly schedule?: boolean;
+    readonly connectors?: boolean;
+    readonly queue?: {
+        readonly publish?: readonly string[];
+        readonly consume?: readonly string[];
+    };
+}
+/** A Finchly manifest, version 1. The schema is in firetail-io/finchly, spec/manifest. */
+export interface Manifest {
+    readonly manifestVersion: 1;
+    readonly platformApi: string;
+    readonly slug: string;
+    readonly name: string;
+    readonly version: string;
+    readonly port: number;
+    readonly healthPath: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly tags?: readonly string[];
+    readonly permissions?: ManifestPermissions;
+    readonly calls?: readonly string[];
+    readonly publicPaths?: readonly PublicPath[];
+    readonly proxyTimeoutSeconds?: number;
+    readonly maxBodyBytes?: number;
+    readonly websocket?: boolean;
+    readonly audit?: "full" | "metadata";
+}
+/**
+ * Check the parts of a manifest this SDK itself depends on.
+ *
+ * This is deliberately not the full schema. The platform runs the full
+ * check when the service registers, and is the authority. The point here is
+ * to stop a container at startup, with a clear message, when the manifest
+ * is missing something the SDK cannot work without.
+ */
+export declare function checkManifest(value: unknown): Manifest;
+/** Read and check the manifest from the container's filesystem. */
+export declare function loadManifest(path?: string): Promise<Manifest>;

package/dist/manifest.js

@@ -0,0 +1,71 @@
+import { readFile } from "node:fs/promises";
+import { DEFAULT_MANIFEST_PATH } from "./config.js";
+import { FinchlyError } from "./errors.js";
+import { MANIFEST_VERSION, SUPPORTED_PLATFORM_API_VERSIONS } from "./platform-api.js";
+const SLUG = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/**
+ * Check the parts of a manifest this SDK itself depends on.
+ *
+ * This is deliberately not the full schema. The platform runs the full
+ * check when the service registers, and is the authority. The point here is
+ * to stop a container at startup, with a clear message, when the manifest
+ * is missing something the SDK cannot work without.
+ */
+export function checkManifest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new FinchlyError("manifest_invalid", "Manifest is not a JSON object");
+    }
+    const m = value;
+    const problems = [];
+    if (m.manifestVersion !== MANIFEST_VERSION) {
+        problems.push(`manifestVersion must be ${MANIFEST_VERSION}`);
+    }
+    if (typeof m.platformApi !== "string") {
+        problems.push("platformApi must be a string");
+    }
+    else if (!SUPPORTED_PLATFORM_API_VERSIONS.includes(m.platformApi)) {
+        problems.push(`platformApi "${m.platformApi}" is not one this SDK speaks (${SUPPORTED_PLATFORM_API_VERSIONS.join(", ")})`);
+    }
+    const slugOk = typeof m.slug === "string" && m.slug.length >= 2 && m.slug.length <= 40 && SLUG.test(m.slug);
+    if (!slugOk) {
+        problems.push("slug must be 2 to 40 lowercase letters, digits and single hyphens, starting with a letter");
+    }
+    if (typeof m.name !== "string" || m.name.length === 0) {
+        problems.push("name must be a non-empty string");
+    }
+    if (typeof m.version !== "string" || m.version.length === 0) {
+        problems.push("version must be a non-empty string");
+    }
+    if (!Number.isInteger(m.port) || m.port < 1 || m.port > 65535) {
+        problems.push("port must be an integer from 1 to 65535");
+    }
+    if (typeof m.healthPath !== "string") {
+        problems.push("healthPath must be a string");
+    }
+    else if (slugOk && !m.healthPath.startsWith(`/${m.slug}/`)) {
+        problems.push(`healthPath must start with /${m.slug}/`);
+    }
+    if (problems.length > 0) {
+        throw new FinchlyError("manifest_invalid", "Manifest is invalid", problems);
+    }
+    return value;
+}
+/** Read and check the manifest from the container's filesystem. */
+export async function loadManifest(path = DEFAULT_MANIFEST_PATH) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new FinchlyError("manifest_unreadable", `Cannot read manifest at ${path}`, [reason]);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new FinchlyError("manifest_invalid", `Manifest at ${path} is not valid JSON`);
+    }
+    return checkManifest(parsed);
+}

package/dist/platform-api.d.ts

@@ -0,0 +1,6 @@
+/** Platform API version this SDK release speaks by default. */
+export declare const PLATFORM_API_VERSION = "v1";
+/** Every platform API version this SDK release can speak. */
+export declare const SUPPORTED_PLATFORM_API_VERSIONS: readonly string[];
+/** Manifest schema version this SDK release reads. */
+export declare const MANIFEST_VERSION = 1;

package/dist/platform-api.js

@@ -0,0 +1,8 @@
+// The platform API is specified in firetail-io/finchly under spec/. This
+// package is one implementation of it and defines no protocol of its own.
+/** Platform API version this SDK release speaks by default. */
+export const PLATFORM_API_VERSION = "v1";
+/** Every platform API version this SDK release can speak. */
+export const SUPPORTED_PLATFORM_API_VERSIONS = Object.freeze(["v1"]);
+/** Manifest schema version this SDK release reads. */
+export const MANIFEST_VERSION = 1;

package/dist/service.d.ts

@@ -0,0 +1,43 @@
+export interface ServiceClientOptions {
+    /** This service's slug. */
+    readonly slug: string;
+    /** The gateway's internal address (PLATFORM_GATEWAY_URL). */
+    readonly gatewayUrl: string;
+    /**
+     * The credential this built-in service was deployed with
+     * (PLATFORM_SERVICE_CREDENTIAL). It is what gets the instance key
+     * accepted. An app has none; its key is accepted when it registers.
+     */
+    readonly credential?: string;
+    /** For tests. */
+    readonly fetch?: typeof fetch;
+    /** For tests. */
+    readonly now?: () => Date;
+}
+export interface CallOptions {
+    /**
+     * The id of the user this call is made for. The target then sees that
+     * user, and this service as the one acting for them. Leave it out to
+     * call as the service itself.
+     */
+    readonly asUser?: string;
+}
+export interface ServiceClient {
+    /**
+     * Make the instance key and have the gateway accept it. Optional: the
+     * first call does this. Call it at startup to fail early instead.
+     */
+    start(): Promise<void>;
+    /** The id of this instance's key, once it has one. */
+    readonly keyId: string | undefined;
+    /** A signed token for a call to `target`. Most code wants `call`. */
+    token(target: string, options?: CallOptions): Promise<string>;
+    /**
+     * Call another service. `path` is the path under the target, starting
+     * with "/". Resolves with the response, whatever its status: a 403 means
+     * this service's manifest does not declare the target in `calls`, or the
+     * user has no access to it.
+     */
+    call(target: string, path: string, init?: RequestInit & CallOptions): Promise<Response>;
+}
+export declare function createServiceClient(options: ServiceClientOptions): ServiceClient;

package/dist/service.js

@@ -0,0 +1,201 @@
+// Calls from this service to another, through the gateway.
+//
+// Services never address each other directly. A call goes to the gateway's
+// internal address with a token this instance signs with its own key; the
+// gateway checks it, decides whether the call is allowed, and forwards it.
+// The token format is in spec/service-token.md and key registration in
+// spec/registration.md, both in firetail-io/finchly.
+import { randomUUID } from "node:crypto";
+import { SignJWT, calculateJwkThumbprint, exportJWK, generateKeyPair } from "jose";
+import { FinchlyError } from "./errors.js";
+const SLUG = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const USER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** The audience of a token meant for the gateway itself. */
+const GATEWAY_AUDIENCE = "gateway";
+const KEYS_PATH = "/_gateway/keys";
+/** How long a token is valid. The specification allows up to 300 seconds. */
+const TOKEN_TTL_SECONDS = 60;
+const REGISTRATION_TIMEOUT_MS = 10_000;
+/** After a call is refused as unauthenticated, wait this long before registering again. */
+const REREGISTER_COOLDOWN_MS = 60_000;
+function invalid(message) {
+    return new FinchlyError("service_call_invalid", message);
+}
+export function createServiceClient(options) {
+    if (!SLUG.test(options.slug))
+        throw invalid(`slug ${JSON.stringify(options.slug)} is not a slug`);
+    const gatewayUrl = options.gatewayUrl.replace(/\/+$/, "");
+    if (!/^https?:\/\//.test(gatewayUrl))
+        throw invalid("gatewayUrl must be an http or https URL");
+    const { slug, credential } = options;
+    const doFetch = options.fetch ?? fetch;
+    const now = options.now ?? (() => new Date());
+    const issuer = `service:${slug}`;
+    let key;
+    let pending;
+    /** Set when a call came back 401: the gateway may no longer know the key. */
+    let doubtedAt;
+    let lastForcedAt = Number.NEGATIVE_INFINITY;
+    async function sign(instance, audience, subject) {
+        const issuedAt = Math.floor(now().getTime() / 1000);
+        return new SignJWT({})
+            .setProtectedHeader({ alg: "ES256", kid: instance.kid, typ: "JWT" })
+            .setIssuer(issuer)
+            .setSubject(subject)
+            .setAudience(audience)
+            .setIssuedAt(issuedAt)
+            .setExpirationTime(issuedAt + TOKEN_TTL_SECONDS)
+            .setJti(randomUUID())
+            .sign(instance.privateKey);
+    }
+    /** Ask the gateway to accept the key, or to extend it. */
+    async function register(instance, authorization, withSlug) {
+        const body = {
+            ...(withSlug ? { slug } : {}),
+            key: { kid: instance.kid, jwk: instance.publicJwk },
+        };
+        try {
+            return await doFetch(`${gatewayUrl}${KEYS_PATH}`, {
+                method: "POST",
+                headers: { authorization, "content-type": "application/json", accept: "application/json" },
+                body: JSON.stringify(body),
+                // The credential goes to the gateway and nowhere a response points.
+                redirect: "error",
+                signal: AbortSignal.timeout(REGISTRATION_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            throw new FinchlyError("gateway_unreachable", "Cannot register this instance's key with the gateway", [
+                err instanceof Error ? err.message : String(err),
+            ]);
+        }
+    }
+    async function accept(instance, response) {
+        let body = {};
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // Reported below, by status.
+        }
+        const expiresAt = typeof body.keyExpiresAt === "string" ? Date.parse(body.keyExpiresAt) : Number.NaN;
+        if (response.status !== 200 || Number.isNaN(expiresAt)) {
+            const reason = typeof body.error === "string" ? body.error : `status ${response.status}`;
+            throw new FinchlyError("service_key_rejected", "The gateway did not accept this instance's key", [reason]);
+        }
+        const nowMs = now().getTime();
+        instance.expiresAt = expiresAt;
+        // Extend it when two thirds of its life has gone.
+        instance.renewAt = nowMs + ((expiresAt - nowMs) * 2) / 3;
+        return instance;
+    }
+    async function withCredential(instance) {
+        if (credential === undefined || credential === "") {
+            throw new FinchlyError("service_key_rejected", "This instance has no key the gateway accepts, and no credential to register one", [
+                "A built-in service is deployed with PLATFORM_SERVICE_CREDENTIAL.",
+                "An app's key is accepted when it registers, which this SDK release cannot do yet.",
+            ]);
+        }
+        return accept(instance, await register(instance, `Service-Credential ${credential}`, true));
+    }
+    async function obtain(force) {
+        const nowMs = now().getTime();
+        if (key === undefined) {
+            const { publicKey, privateKey } = await generateKeyPair("ES256");
+            const { kty, crv, x, y } = await exportJWK(publicKey);
+            const publicJwk = { kty: kty, crv: crv, x: x, y: y };
+            const fresh = {
+                kid: await calculateJwkThumbprint(publicJwk),
+                privateKey,
+                publicJwk,
+                expiresAt: 0,
+                renewAt: 0,
+            };
+            key = await withCredential(fresh);
+            return key;
+        }
+        if (!force && nowMs < key.renewAt)
+            return key;
+        if (!force && nowMs < key.expiresAt) {
+            // Still accepted: extend it with a token it signs itself.
+            const response = await register(key, `Bearer ${await sign(key, GATEWAY_AUDIENCE, issuer)}`, false);
+            if (response.status !== 401)
+                return accept(key, response);
+            await response.body?.cancel();
+        }
+        // Expired, or the gateway no longer knows it: start again from the credential.
+        return withCredential(key);
+    }
+    /** The instance key, registered and current. Concurrent callers share one registration. */
+    function instanceKey() {
+        const nowMs = now().getTime();
+        // Only a credential can re-register, so only then is it worth trying.
+        const force = doubtedAt !== undefined && Boolean(credential) && nowMs - lastForcedAt >= REREGISTER_COOLDOWN_MS;
+        if (key !== undefined && !force && nowMs < key.renewAt)
+            return Promise.resolve(key);
+        if (pending === undefined) {
+            if (force) {
+                lastForcedAt = nowMs;
+                doubtedAt = undefined;
+            }
+            pending = obtain(force).finally(() => {
+                pending = undefined;
+            });
+        }
+        return pending;
+    }
+    function subjectFor(callOptions) {
+        const user = callOptions?.asUser;
+        if (user === undefined)
+            return issuer;
+        if (!USER_ID.test(user))
+            throw invalid("asUser must be a user's platform id");
+        return user;
+    }
+    return {
+        async start() {
+            await instanceKey();
+        },
+        get keyId() {
+            return key?.kid;
+        },
+        async token(target, callOptions) {
+            if (!SLUG.test(target))
+                throw invalid(`target ${JSON.stringify(target)} is not a slug`);
+            const subject = subjectFor(callOptions);
+            return sign(await instanceKey(), target, subject);
+        },
+        async call(target, path, init = {}) {
+            if (!SLUG.test(target))
+                throw invalid(`target ${JSON.stringify(target)} is not a slug`);
+            // The path is joined as text. It must not be able to climb out of the target.
+            if (!path.startsWith("/") || path.includes("\\") || /(^|\/)\.\.?(\/|$|\?)/.test(path.split("?")[0] ?? "")) {
+                throw invalid('path must start with "/" and contain no "." or ".." segments');
+            }
+            const { asUser, ...request } = init;
+            const subject = subjectFor(asUser !== undefined ? { asUser } : undefined);
+            const token = await sign(await instanceKey(), target, subject);
+            const headers = new Headers(request.headers);
+            // Whatever the caller set, the gateway reads this one.
+            headers.set("authorization", `Bearer ${token}`);
+            let response;
+            try {
+                // A redirect from the target is handed back, not followed: the
+                // token is for the target and goes nowhere else.
+                response = await doFetch(`${gatewayUrl}/${target}${path}`, { redirect: "manual", ...request, headers });
+            }
+            catch (err) {
+                const name = err?.name;
+                // The caller's own abort or timeout is theirs to handle.
+                if (name === "AbortError" || name === "TimeoutError")
+                    throw err;
+                throw new FinchlyError("gateway_unreachable", `Cannot reach ${target} through the gateway`, [
+                    err instanceof Error ? err.message : String(err),
+                ]);
+            }
+            if (response.status === 401)
+                doubtedAt = now().getTime();
+            return response;
+        },
+    };
+}

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** Package name, as reported to the platform at registration. */
+export declare const SDK_NAME: string;
+/** Package version, as reported to the platform at registration. */
+export declare const SDK_VERSION: string;

package/dist/version.js

@@ -0,0 +1,8 @@
+import { createRequire } from "node:module";
+// package.json sits one level above both src/ and dist/, so this resolves
+// the same way from source and from the published build.
+const pkg = createRequire(import.meta.url)("../package.json");
+/** Package name, as reported to the platform at registration. */
+export const SDK_NAME = pkg.name;
+/** Package version, as reported to the platform at registration. */
+export const SDK_VERSION = pkg.version;

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Node SDK for the Finchly platform",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "test": "npm run build && node --test \"test/**/*.test.mjs\"",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/firetail-io/finchly-sdk-js.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "~5.9.3"
+  },
+  "dependencies": {
+    "jose": "^6.2.17"
+  }
+}