@firetail/finchly 0.0.1 → 0.0.5

package/CHANGELOG.md

@@ -4,11 +4,28 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 0.0.5 - 2026-11-12
+
+- The README covers using the SDK only. Notes for people working on the
+  SDK are no longer part of the package.
+
+## 0.0.4 - 2026-11-12
+
+- 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`.
+- 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.2 and 0.0.3 were not published.
+
 ## 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.
+The first release.
 
 - Package skeleton under its final name.
 - `loadConfig`: read and validate the `PLATFORM_*` settings.

package/README.md

@@ -1,6 +1,6 @@
 # @firetail/finchly
 
-Node SDK for the [Finchly](https://github.com/firetail-io/finchly) platform.
+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.
@@ -9,7 +9,7 @@ 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`
+`FireTail-io/finchly` under `spec/`. This release speaks platform API `v1`
 (draft).
 
 ## Install
@@ -69,7 +69,7 @@ try {
 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`.
+`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
@@ -115,11 +115,65 @@ 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`.
+`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`.
+### 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.5` |
+| `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
 
@@ -142,8 +196,8 @@ not leak them.
 | `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` |
+| `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 |
@@ -155,54 +209,6 @@ not leak them.
 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
-```
+## Changes
 
-`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.
+See `CHANGELOG.md`.

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";
+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

package/dist/identity.js

@@ -4,6 +4,7 @@
 import { createLocalJWKSet, createRemoteJWKSet, decodeProtectedHeader, errors, jwtVerify } from "jose";
 import { FinchlyError, IdentityError } from "./errors.js";
 import { SUPPORTED_PLATFORM_API_VERSIONS } from "./platform-api.js";
+import { SDK_REQUEST_HEADERS } from "./request-headers.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"];
@@ -135,7 +136,10 @@ export function createIdentityVerifier(options) {
         const url = `${gatewayUrl}/_gateway/.well-known/platform.json`;
         let body;
         try {
-            const response = await fetch(url, { signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS) });
+            const response = await fetch(url, {
+                headers: SDK_REQUEST_HEADERS,
+                signal: AbortSignal.timeout(GATEWAY_TIMEOUT_MS),
+            });
             if (!response.ok) {
                 throw new Error(`HTTP ${response.status}`);
             }
@@ -159,6 +163,7 @@ export function createIdentityVerifier(options) {
                 cacheMaxAge: KEY_CACHE_MS,
                 cooldownDuration: KEY_REFETCH_COOLDOWN_MS,
                 timeoutDuration: GATEWAY_TIMEOUT_MS,
+                headers: SDK_REQUEST_HEADERS,
             }),
         };
     }

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export type { Identity, IdentityVerifier, IdentityVerifierOptions } from "./iden
 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 { PLATFORM_API_VERSION_HEADER, SDK_HEADER, SDK_REQUEST_HEADERS, SDK_VERSION_HEADER, } from "./request-headers.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

@@ -3,5 +3,6 @@ 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 { PLATFORM_API_VERSION_HEADER, SDK_HEADER, SDK_REQUEST_HEADERS, SDK_VERSION_HEADER, } from "./request-headers.js";
+export { createServiceClient, enrolmentFrom } from "./service.js";
 export { SDK_NAME, SDK_VERSION } from "./version.js";

package/dist/request-headers.d.ts

@@ -0,0 +1,8 @@
+/** Header naming the SDK package, for example `@firetail/finchly`. */
+export declare const SDK_HEADER = "x-platform-sdk";
+/** Header carrying the SDK's version, for example `0.0.3`. */
+export declare const SDK_VERSION_HEADER = "x-platform-sdk-version";
+/** Header carrying the platform API version the SDK speaks, for example `v1`. */
+export declare const PLATFORM_API_VERSION_HEADER = "x-platform-api-version";
+/** The three headers, as sent on every request to the gateway. */
+export declare const SDK_REQUEST_HEADERS: Readonly<Record<string, string>>;

package/dist/request-headers.js

@@ -0,0 +1,16 @@
+// What every request this SDK makes to the platform carries, so the
+// platform can tell which SDK and which release it is talking to.
+import { PLATFORM_API_VERSION } from "./platform-api.js";
+import { SDK_NAME, SDK_VERSION } from "./version.js";
+/** Header naming the SDK package, for example `@firetail/finchly`. */
+export const SDK_HEADER = "x-platform-sdk";
+/** Header carrying the SDK's version, for example `0.0.3`. */
+export const SDK_VERSION_HEADER = "x-platform-sdk-version";
+/** Header carrying the platform API version the SDK speaks, for example `v1`. */
+export const PLATFORM_API_VERSION_HEADER = "x-platform-api-version";
+/** The three headers, as sent on every request to the gateway. */
+export const SDK_REQUEST_HEADERS = Object.freeze({
+    [SDK_HEADER]: SDK_NAME,
+    [SDK_VERSION_HEADER]: SDK_VERSION,
+    [PLATFORM_API_VERSION_HEADER]: PLATFORM_API_VERSION,
+});

package/dist/service.d.ts

@@ -1,3 +1,5 @@
+import type { PlatformConfig } from "./config.js";
+import type { Manifest } from "./manifest.js";
 export interface ServiceClientOptions {
     /** This service's slug. */
     readonly slug: string;
@@ -9,11 +11,40 @@ export interface ServiceClientOptions {
      * accepted. An app has none; its key is accepted when it registers.
      */
     readonly credential?: string;
+    /**
+     * How an app gets its instance key accepted: by registering itself. Use
+     * `enrolmentFrom` to build this from the platform settings and the
+     * manifest. Ignored when `credential` is set.
+     */
+    readonly enrolment?: Enrolment;
     /** For tests. */
     readonly fetch?: typeof fetch;
     /** For tests. */
     readonly now?: () => Date;
 }
+/** What an app presents to register itself. See spec/registration.md, section 2. */
+export interface Enrolment {
+    /** The enrolment token an administrator issued for this app's slug (PLATFORM_ENROLMENT_TOKEN). */
+    readonly token: string;
+    /** The app's manifest, as loaded from its image. */
+    readonly manifest: Readonly<Record<string, unknown>>;
+    /** Where the gateway can reach this app, for example http://expense-tracker.apps.local:3005. */
+    readonly address: string;
+    /** The manifest's signature bundle, when the release is signed. */
+    readonly bundle?: string;
+}
+/**
+ * Build what an app presents to register itself, from its platform
+ * settings and manifest. Returns undefined if the app was given no
+ * enrolment token, which is right for a built-in service.
+ *
+ * The address is PLATFORM_APP_ADDRESS if set. Otherwise it is this
+ * machine's hostname and the manifest's port, which is right when the
+ * container's hostname is the name the gateway resolves.
+ */
+export declare function enrolmentFrom(config: PlatformConfig, manifest: Manifest, options?: {
+    readonly bundle?: string;
+}): Enrolment | undefined;
 export interface CallOptions {
     /**
      * The id of the user this call is made for. The target then sees that

package/dist/service.js

@@ -7,17 +7,41 @@
 // spec/registration.md, both in firetail-io/finchly.
 import { randomUUID } from "node:crypto";
 import { SignJWT, calculateJwkThumbprint, exportJWK, generateKeyPair } from "jose";
+import { hostname } from "node:os";
 import { FinchlyError } from "./errors.js";
+import { PLATFORM_API_VERSION } from "./platform-api.js";
+import { SDK_REQUEST_HEADERS } from "./request-headers.js";
+import { SDK_NAME, SDK_VERSION } from "./version.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";
+const ENROL_PATH = "/_gateway/enrol";
 /** 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;
+/**
+ * Build what an app presents to register itself, from its platform
+ * settings and manifest. Returns undefined if the app was given no
+ * enrolment token, which is right for a built-in service.
+ *
+ * The address is PLATFORM_APP_ADDRESS if set. Otherwise it is this
+ * machine's hostname and the manifest's port, which is right when the
+ * container's hostname is the name the gateway resolves.
+ */
+export function enrolmentFrom(config, manifest, options = {}) {
+    if (!config.enrolmentToken)
+        return undefined;
+    return {
+        token: config.enrolmentToken,
+        manifest: manifest,
+        address: config.appAddress ?? `http://${hostname()}:${manifest.port}`,
+        ...(options.bundle !== undefined ? { bundle: options.bundle } : {}),
+    };
+}
 function invalid(message) {
     return new FinchlyError("service_call_invalid", message);
 }
@@ -32,6 +56,10 @@ export function createServiceClient(options) {
     const now = options.now ?? (() => new Date());
     const issuer = `service:${slug}`;
     let key;
+    /** A key pair made but not yet accepted. */
+    let candidate;
+    /** While a release waits for approval: when the gateway said to ask again, in ms. */
+    let enrolNotBeforeMs = 0;
     let pending;
     /** Set when a call came back 401: the gateway may no longer know the key. */
     let doubtedAt;
@@ -57,7 +85,7 @@ export function createServiceClient(options) {
         try {
             return await doFetch(`${gatewayUrl}${KEYS_PATH}`, {
                 method: "POST",
-                headers: { authorization, "content-type": "application/json", accept: "application/json" },
+                headers: { ...SDK_REQUEST_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",
@@ -89,29 +117,91 @@ export function createServiceClient(options) {
         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.",
+    /** An app registers itself, which is also what gets its key accepted. */
+    async function enrol(instance, enrolment) {
+        const nowMs = now().getTime();
+        if (nowMs < enrolNotBeforeMs) {
+            throw new FinchlyError("app_pending_approval", "This app's release is waiting for an administrator's approval", [
+                `asking again in ${Math.ceil((enrolNotBeforeMs - nowMs) / 1000)} seconds`,
             ]);
         }
-        return accept(instance, await register(instance, `Service-Credential ${credential}`, true));
+        let response;
+        try {
+            response = await doFetch(`${gatewayUrl}${ENROL_PATH}`, {
+                method: "POST",
+                headers: {
+                    ...SDK_REQUEST_HEADERS,
+                    authorization: `Enrol ${enrolment.token}`,
+                    "content-type": "application/json",
+                    accept: "application/json",
+                },
+                body: JSON.stringify({
+                    platformApi: PLATFORM_API_VERSION,
+                    manifest: enrolment.manifest,
+                    ...(enrolment.bundle !== undefined ? { bundle: enrolment.bundle } : {}),
+                    address: enrolment.address,
+                    key: { kid: instance.kid, jwk: instance.publicJwk },
+                    sdk: { name: SDK_NAME, version: SDK_VERSION },
+                }),
+                // The token 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 app with the gateway", [
+                err instanceof Error ? err.message : String(err),
+            ]);
+        }
+        if (response.status === 200)
+            return accept(instance, response);
+        let body = {};
+        try {
+            body = (await response.json());
+        }
+        catch {
+            // Reported below, by status.
+        }
+        if (response.status === 202) {
+            const seconds = typeof body.retryAfterSeconds === "number" && body.retryAfterSeconds > 0 ? body.retryAfterSeconds : 30;
+            // Do not ask again before the gateway said to.
+            enrolNotBeforeMs = nowMs + seconds * 1000;
+            throw new FinchlyError("app_pending_approval", "This app's release is waiting for an administrator's approval", [
+                `asking again in ${seconds} seconds`,
+            ]);
+        }
+        const reasons = Array.isArray(body.reasons) ? body.reasons.filter((r) => typeof r === "string") : [];
+        throw new FinchlyError("app_registration_refused", "The platform refused to register this app", reasons.length > 0 ? reasons : [typeof body.error === "string" ? body.error : `status ${response.status}`]);
+    }
+    /** Get a key accepted from scratch: with the credential, or by registering. */
+    async function firstRegistration(instance) {
+        if (credential)
+            return accept(instance, await register(instance, `Service-Credential ${credential}`, true));
+        if (options.enrolment)
+            return enrol(instance, options.enrolment);
+        throw new FinchlyError("service_key_rejected", "This instance has no key the gateway accepts, and no way to get one accepted", [
+            "A built-in service is deployed with PLATFORM_SERVICE_CREDENTIAL.",
+            "An app registers itself: pass `enrolment`, built with enrolmentFrom(config, manifest).",
+        ]);
     }
     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);
+            if (candidate === 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 };
+                candidate = {
+                    kid: await calculateJwkThumbprint(publicJwk),
+                    privateKey,
+                    publicJwk,
+                    expiresAt: 0,
+                    renewAt: 0,
+                };
+            }
+            // The same key pair is offered until it is accepted: a release that
+            // is waiting for approval is asked about again with it.
+            key = await firstRegistration(candidate);
             return key;
         }
         if (!force && nowMs < key.renewAt)
@@ -123,14 +213,16 @@ export function createServiceClient(options) {
                 return accept(key, response);
             await response.body?.cancel();
         }
-        // Expired, or the gateway no longer knows it: start again from the credential.
-        return withCredential(key);
+        // Expired, or the gateway no longer knows it: get it accepted again from scratch.
+        return firstRegistration(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;
+        // Worth trying only if there is a way to register again.
+        const force = doubtedAt !== undefined &&
+            Boolean(credential || options.enrolment) &&
+            nowMs - lastForcedAt >= REREGISTER_COOLDOWN_MS;
         if (key !== undefined && !force && nowMs < key.renewAt)
             return Promise.resolve(key);
         if (pending === undefined) {
@@ -178,6 +270,9 @@ export function createServiceClient(options) {
             const headers = new Headers(request.headers);
             // Whatever the caller set, the gateway reads this one.
             headers.set("authorization", `Bearer ${token}`);
+            // And these say which SDK is calling, which is not the caller's to choose.
+            for (const [name, value] of Object.entries(SDK_REQUEST_HEADERS))
+                headers.set(name, value);
             let response;
             try {
                 // A redirect from the target is handed back, not followed: the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.1",
+  "version": "0.0.5",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/firetail-io/finchly-sdk-js.git"
+    "url": "git+https://github.com/FireTail-io/finchly-sdk-js.git"
   },
   "publishConfig": {
     "access": "public"