@firetail/finchly 0.0.0-stage → 0.0.4

package/dist/service.js

@@ -0,0 +1,296 @@
+// 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 { 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);
+}
+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;
+    /** 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;
+    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: { ...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",
+                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;
+    }
+    /** 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`,
+            ]);
+        }
+        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) {
+            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)
+            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: 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();
+        // 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) {
+            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}`);
+            // 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
+                // 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.4",
+  "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"
+  }
+}