@firetail/finchly 0.0.0-stage → 0.0.4

package/dist/identity.js

@@ -0,0 +1,237 @@
+// 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";
+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"];
+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, {
+                headers: SDK_REQUEST_HEADERS,
+                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,
+                headers: SDK_REQUEST_HEADERS,
+            }),
+        };
+    }
+    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,13 @@
+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 { 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

@@ -0,0 +1,8 @@
+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 { 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/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/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

@@ -0,0 +1,74 @@
+import type { PlatformConfig } from "./config.js";
+import type { Manifest } from "./manifest.js";
+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;
+    /**
+     * 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
+     * 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;