initiative-plugin-sdk 2.0.0

package/dist/tokens.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Verifying the tokens Initiative signs when it reaches the plug-in.
+ *
+ * Both kinds are RS256 JWTs signed with the deployment's key and published in
+ * its JWKS at `/api/v1/plugin-platform/jwks.json`:
+ *
+ * - **Context token**, on every call to the plug-in (`Authorization: Bearer …`).
+ *   Scope `endpoint` is a call to one endpoint, named by `endpoint_id`; scope
+ *   `lifecycle` is a call to one hook, named by `hook`. When another plug-in made
+ *   the call through Initiative it also carries `act` (that plug-in), `actor`,
+ *   `member` and, when the caller was confined to one, `initiative_id`.
+ * - **Handoff token**, when a member opens one of the plug-in's surfaces. It names
+ *   the member (`sub`), the surface, and the initiative it was opened in. It is
+ *   for one use.
+ *
+ * Each is checked the same way: the `kid` against the deployment's JWKS, the
+ * signature, `iss` = `initiative`, `aud` = `initiative-plugin:<public id>`, and
+ * `exp`/`iat` against the clock with a small leeway.
+ */
+import { type KeyObject } from "node:crypto";
+import { type ActorKind } from "./contract.js";
+/**
+ * What a context token authorizes.
+ *
+ * `endpoint` covers every call to an endpoint your plug-in declares; the id says
+ * which. `lifecycle` is Initiative calling one of your hooks about an
+ * installation; `hook` says which.
+ */
+export type ContextScope = "endpoint" | "lifecycle";
+/** Where the deployment publishes its verification keys. */
+export declare const JWKS_PATH = "/api/v1/plugin-platform/jwks.json";
+/** How long a fetched key set is reused before a refetch is considered. */
+export declare const JWKS_CACHE_SECONDS = 300;
+/** The `iss` every token from Initiative carries. */
+export declare const INITIATIVE_ISSUER = "initiative";
+/** `typ` on a call to an endpoint or a hook (RFC 8725 §3.11). */
+export declare const CONTEXT_TOKEN_TYPE = "initiative-context+jwt";
+/** `typ` on a page handoff. */
+export declare const HANDOFF_TOKEN_TYPE = "initiative-handoff+jwt";
+/** Claims every token from Initiative carries. */
+export interface InitiativeTokenClaims {
+    jti: string;
+    iss: string;
+    aud: string;
+    iat: number;
+    exp: number;
+    /**
+     * The community, by the reference your installation knows it by. Stable for
+     * your installation, so it is what your own rows key on.
+     */
+    community_ref: string;
+    /** The installation within that community. */
+    plugin_install_id: number;
+}
+export interface ContextClaims extends InitiativeTokenClaims {
+    scope: ContextScope;
+    /** Which endpoint this call is for. Present when the scope is `endpoint`. */
+    endpoint_id?: string;
+    /** Which hook this call is for. Present when the scope is `lifecycle`. */
+    hook?: string;
+    /**
+     * Connection id → the opaque handle you ask Initiative for an access token
+     * with. Present only where the call depends on a connection. On a call from
+     * another plug-in it holds only what the actor may use: the member's own
+     * connections for a `member` call, the community's for an `installation`
+     * one.
+     */
+    connection_refs?: Record<string, string>;
+    /**
+     * Present when another plug-in made this call through Initiative: that plug-in's
+     * public id, as `act.sub` (RFC 8693 §4.1). Absent when Initiative itself
+     * called, for a widget.
+     */
+    act?: {
+        sub: string;
+    };
+    /**
+     * On a call from another plug-in: whose behalf it is on. `installation` is the
+     * community; `member` is the member named in {@link ContextClaims.member}.
+     */
+    actor?: ActorKind;
+    /**
+     * On a `member` call: the member, by the reference your installation knows
+     * them by. The calling plug-in never sees it.
+     */
+    member?: string;
+    /**
+     * On a call from another plug-in whose token is confined to one initiative: that
+     * initiative. Your plug-in is placed there too.
+     */
+    initiative_id?: number;
+}
+export interface HandoffClaims extends InitiativeTokenClaims {
+    /** The member, by their reference for your installation. */
+    sub: string;
+    /** Which of your surfaces was opened. */
+    surface_id: string;
+    /** The initiative it was opened in. Absent when opened for the whole community. */
+    initiative_id?: number;
+    /** Whether the member administers the community. */
+    community_admin?: boolean;
+}
+export declare class ContextTokenError extends Error {
+}
+/** The audience a token for `publicId` names. */
+export declare function audienceFor(publicId: string): string;
+/**
+ * Fetches and caches a deployment's published verification keys, by `kid`.
+ *
+ * An unknown `kid` refetches the set once, so a key rotation (which publishes
+ * both keys for a while) resolves without a restart. A second miss inside the
+ * same window does not refetch again.
+ */
+export declare class JwksCache {
+    private readonly options;
+    private readonly cache;
+    constructor(options?: {
+        /** Injectable for tests and for a runtime with its own fetch. */
+        fetchImpl?: typeof fetch;
+        /** Milliseconds since the epoch. */
+        now?: () => number;
+        cacheSeconds?: number;
+        /** Which document to read. Defaults to {@link JWKS_PATH}. */
+        path?: string;
+    });
+    /** The key for `kid`, fetching the set if it is unknown or stale. */
+    keyFor(baseUrl: string, kid: string): Promise<KeyObject>;
+    private load;
+}
+export interface VerifyOptions {
+    /** Your plug-in's public id. The audience must name it. */
+    publicId: string;
+    /** The deployment, for key lookup: its origin or its API base. */
+    baseUrl: string;
+    jwks: JwksCache;
+    /** Defaults to {@link INITIATIVE_ISSUER}. */
+    issuer?: string;
+    /** Milliseconds since the epoch. */
+    now?: () => number;
+    /** Tolerance for clock skew, in seconds. Default 30. */
+    leewaySeconds?: number;
+}
+/** Verify a context token and return its claims. */
+export declare function verifyContextToken(token: string, options: VerifyOptions): Promise<ContextClaims>;
+/**
+ * Verify a handoff token and return its claims.
+ *
+ * Single use is yours to enforce: record `jti` until `exp` and refuse a token
+ * whose `jti` you have already seen.
+ */
+export declare function verifyHandoffToken(token: string, options: VerifyOptions): Promise<HandoffClaims>;
+/**
+ * Verify the token on a call to one of your hooks, and return its claims.
+ *
+ * Refuses anything but a `lifecycle` token, and, when `hook` is given, one
+ * minted for another hook: a token for `revoke` cannot be spent on
+ * `after_connect`.
+ */
+export declare function verifyLifecycleToken(token: string, options: VerifyOptions & {
+    hook?: string;
+}): Promise<ContextClaims>;

package/dist/tokens.js

@@ -0,0 +1,215 @@
+/**
+ * Verifying the tokens Initiative signs when it reaches the plug-in.
+ *
+ * Both kinds are RS256 JWTs signed with the deployment's key and published in
+ * its JWKS at `/api/v1/plugin-platform/jwks.json`:
+ *
+ * - **Context token**, on every call to the plug-in (`Authorization: Bearer …`).
+ *   Scope `endpoint` is a call to one endpoint, named by `endpoint_id`; scope
+ *   `lifecycle` is a call to one hook, named by `hook`. When another plug-in made
+ *   the call through Initiative it also carries `act` (that plug-in), `actor`,
+ *   `member` and, when the caller was confined to one, `initiative_id`.
+ * - **Handoff token**, when a member opens one of the plug-in's surfaces. It names
+ *   the member (`sub`), the surface, and the initiative it was opened in. It is
+ *   for one use.
+ *
+ * Each is checked the same way: the `kid` against the deployment's JWKS, the
+ * signature, `iss` = `initiative`, `aud` = `initiative-plugin:<public id>`, and
+ * `exp`/`iat` against the clock with a small leeway.
+ */
+import { createPublicKey, createVerify } from "node:crypto";
+import { ACTOR_KINDS } from "./contract.js";
+/** Where the deployment publishes its verification keys. */
+export const JWKS_PATH = "/api/v1/plugin-platform/jwks.json";
+/** How long a fetched key set is reused before a refetch is considered. */
+export const JWKS_CACHE_SECONDS = 300;
+/** The `iss` every token from Initiative carries. */
+export const INITIATIVE_ISSUER = "initiative";
+/** `typ` on a call to an endpoint or a hook (RFC 8725 §3.11). */
+export const CONTEXT_TOKEN_TYPE = "initiative-context+jwt";
+/** `typ` on a page handoff. */
+export const HANDOFF_TOKEN_TYPE = "initiative-handoff+jwt";
+export class ContextTokenError extends Error {
+}
+/** The audience a token for `publicId` names. */
+export function audienceFor(publicId) {
+    return `initiative-plugin:${publicId}`;
+}
+/**
+ * Fetches and caches a deployment's published verification keys, by `kid`.
+ *
+ * An unknown `kid` refetches the set once, so a key rotation (which publishes
+ * both keys for a while) resolves without a restart. A second miss inside the
+ * same window does not refetch again.
+ */
+export class JwksCache {
+    options;
+    cache = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** The key for `kid`, fetching the set if it is unknown or stale. */
+    async keyFor(baseUrl, kid) {
+        const document = new URL(this.options.path ?? JWKS_PATH, baseUrl).toString();
+        const entry = this.cache.get(document);
+        const now = this.options.now?.() ?? Date.now();
+        const ttl = (this.options.cacheSeconds ?? JWKS_CACHE_SECONDS) * 1000;
+        const fresh = entry !== undefined && now - entry.fetchedAt < ttl;
+        if (fresh) {
+            const cached = entry.keys.get(kid);
+            if (cached)
+                return cached;
+            if (entry.refetched)
+                return missing(document, entry.keys, kid);
+        }
+        const keys = await this.load(document);
+        this.cache.set(document, { keys, fetchedAt: now, refetched: fresh });
+        const found = keys.get(kid);
+        if (!found)
+            return missing(document, keys, kid);
+        return found;
+    }
+    async load(document) {
+        const doFetch = this.options.fetchImpl ?? fetch;
+        const response = await doFetch(document);
+        if (response.status === 404)
+            return new Map();
+        if (!response.ok) {
+            throw new ContextTokenError(`jwks fetch failed with ${response.status}`);
+        }
+        const parsed = (await response.json());
+        const keys = new Map();
+        for (const jwk of parsed.keys ?? []) {
+            if (jwk.kty !== "RSA" || !jwk.kid || !jwk.n || !jwk.e)
+                continue;
+            keys.set(jwk.kid, createPublicKey({ key: jwk, format: "jwk" }));
+        }
+        return keys;
+    }
+}
+/** The same refusal for "no keys published" and "no such key". */
+function missing(document, keys, kid) {
+    throw new ContextTokenError(keys.size === 0
+        ? `${document} published no keys`
+        : `no verification key published for kid ${kid}`);
+}
+/** Verify a context token and return its claims. */
+export async function verifyContextToken(token, options) {
+    const claims = (await verifyInitiativeToken(token, options, CONTEXT_TOKEN_TYPE));
+    if (claims.scope !== "endpoint" && claims.scope !== "lifecycle") {
+        throw new ContextTokenError(`not a context token (scope ${String(claims.scope)})`);
+    }
+    checkCaller(claims);
+    return claims;
+}
+/**
+ * The claims naming another plug-in's call, checked for shape: an `act` names the
+ * caller, an `actor` is one of the two kinds, and a `member` call names its
+ * member.
+ */
+function checkCaller(claims) {
+    if (claims.act !== undefined) {
+        const act = claims.act;
+        if (typeof act !== "object" ||
+            act === null ||
+            typeof act.sub !== "string" ||
+            !act.sub) {
+            throw new ContextTokenError("act names no calling plug-in");
+        }
+    }
+    if (claims.actor !== undefined && !ACTOR_KINDS.includes(claims.actor)) {
+        throw new ContextTokenError(`unknown actor ${String(claims.actor)}`);
+    }
+    if (claims.actor === "member" && (typeof claims.member !== "string" || !claims.member)) {
+        throw new ContextTokenError("a member call names no member");
+    }
+    if (claims.initiative_id !== undefined &&
+        (!Number.isInteger(claims.initiative_id) || claims.initiative_id <= 0)) {
+        throw new ContextTokenError("initiative_id is not an initiative");
+    }
+}
+/**
+ * Verify a handoff token and return its claims.
+ *
+ * Single use is yours to enforce: record `jti` until `exp` and refuse a token
+ * whose `jti` you have already seen.
+ */
+export async function verifyHandoffToken(token, options) {
+    const claims = (await verifyInitiativeToken(token, options, HANDOFF_TOKEN_TYPE));
+    if (typeof claims.sub !== "string" || !claims.sub) {
+        throw new ContextTokenError("handoff token names no member");
+    }
+    if (typeof claims.surface_id !== "string" || !claims.surface_id) {
+        throw new ContextTokenError("handoff token names no surface");
+    }
+    return claims;
+}
+/**
+ * Verify the token on a call to one of your hooks, and return its claims.
+ *
+ * Refuses anything but a `lifecycle` token, and, when `hook` is given, one
+ * minted for another hook: a token for `revoke` cannot be spent on
+ * `after_connect`.
+ */
+export async function verifyLifecycleToken(token, options) {
+    const claims = await verifyContextToken(token, options);
+    if (claims.scope !== "lifecycle") {
+        throw new ContextTokenError(`not a lifecycle token (scope ${String(claims.scope)})`);
+    }
+    if (options.hook !== undefined && claims.hook !== options.hook) {
+        throw new ContextTokenError(`token is for hook ${String(claims.hook)}, not ${options.hook}`);
+    }
+    return claims;
+}
+/** Type, signature, issuer, audience and time: everything the kinds share. */
+async function verifyInitiativeToken(token, options, typ) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new ContextTokenError("not a JWT");
+    }
+    const [rawHeader, rawPayload, rawSignature] = parts;
+    const header = decodeJson(rawHeader);
+    if (header.typ !== typ) {
+        throw new ContextTokenError(`token is typed ${String(header.typ)}, not ${typ}`);
+    }
+    if (header.alg !== "RS256") {
+        throw new ContextTokenError(`unexpected algorithm ${header.alg}`);
+    }
+    if (!header.kid) {
+        throw new ContextTokenError("token names no key");
+    }
+    const key = await options.jwks.keyFor(options.baseUrl, header.kid);
+    const verifier = createVerify("RSA-SHA256");
+    verifier.update(`${rawHeader}.${rawPayload}`);
+    verifier.end();
+    if (!verifier.verify(key, Buffer.from(rawSignature, "base64url"))) {
+        throw new ContextTokenError("signature did not verify");
+    }
+    const claims = decodeJson(rawPayload);
+    const expected = audienceFor(options.publicId);
+    if (claims.aud !== expected) {
+        throw new ContextTokenError(`token is for ${claims.aud}, not ${expected}`);
+    }
+    const issuer = options.issuer ?? INITIATIVE_ISSUER;
+    if (claims.iss !== issuer) {
+        throw new ContextTokenError(`token is from ${claims.iss}, not ${issuer}`);
+    }
+    const seconds = Math.floor((options.now?.() ?? Date.now()) / 1000);
+    const leeway = options.leewaySeconds ?? 30;
+    if (typeof claims.exp !== "number" || claims.exp + leeway < seconds) {
+        throw new ContextTokenError("token has expired");
+    }
+    if (typeof claims.iat === "number" && claims.iat - leeway > seconds) {
+        throw new ContextTokenError("token is not valid yet");
+    }
+    return claims;
+}
+function decodeJson(segment) {
+    try {
+        return JSON.parse(Buffer.from(segment, "base64url").toString("utf-8"));
+    }
+    catch {
+        throw new ContextTokenError("not a JWT");
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"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"}

package/dist/validate.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Checking a manifest before a deployment does.
+ *
+ * **Schema-valid is necessary, not sufficient.** Some rules are not expressible
+ * in JSON Schema and are checked by the platform on publish: cross-references
+ * (the endpoint a widget binds, a `requires` term's connection, an endpoint's
+ * service prefix), the features/blocks cross-check in both directions, UTF-8
+ * byte-size caps, the rules tying a connection's `flow` and `token` to its
+ * scope and fields, what a vendor `setup` writes to, and the bounds and unique
+ * ids of `schedules`.
+ *
+ * {@link validateManifest} runs the schema and then every one of those except
+ * the byte caps. It also reports every term the contract does not declare: a
+ * deployment drops such a term rather than refusing the manifest, so a
+ * misspelt or retired field would otherwise do nothing without saying so. And
+ * it adds one rule the platform does not check: an endpoint's `identity` must
+ * name returns that endpoint actually sends.
+ *
+ * For a declarative plug-in it also parses every JSONata expression, and checks
+ * that a plug-in is one kind or the other, what its requests and steps name, and
+ * the hosts it calls.
+ */
+import { type Manifest } from "./contract.js";
+/** Where a plug-in serves its manifest document. */
+export declare const MANIFEST_PATH = "/.well-known/initiative-plugin.json";
+/** The wire protocol this SDK speaks. */
+export declare const PLUGIN_PROTOCOL_VERSION = 1;
+/**
+ * The document served at {@link MANIFEST_PATH}, of which {@link Manifest} is one
+ * field: the plug-in's identity beside what it declares it can do. A registrar
+ * refuses anything without a `protocol_version`, a `public_id`, a `kind` and a
+ * `definition`.
+ */
+export interface PluginDocument {
+    protocol_version: number;
+    /** `<publisher>.<slug>`, the same id `definition.service.public_id` carries. */
+    public_id: string;
+    kind: "plugin";
+    /** The catalog id: publisher-assigned, immutable, never reused. */
+    uid?: string;
+    name?: string;
+    definition: Manifest;
+}
+/**
+ * The document to serve at {@link MANIFEST_PATH}. Serve the same bytes every
+ * time: a deployment hashes what it fetches and re-checks it.
+ */
+export declare function pluginDocument(manifest: Manifest, options?: {
+    uid?: string;
+    name?: string;
+}): PluginDocument;
+/**
+ * Check a whole served document — the envelope, then the manifest inside it.
+ *
+ * {@link validateManifest} checks what a plug-in declares; this checks what a
+ * registrar will actually fetch. Use it on the bytes you serve.
+ */
+export declare function validateDocument(document: unknown): ValidationProblem[];
+/** The generated schema, read from disk once. */
+export declare function manifestSchema(): Record<string, unknown>;
+export interface ValidationProblem {
+    /** A JSON Pointer-ish path into the manifest. */
+    where: string;
+    message: string;
+}
+/**
+ * Everything this side can check: the schema, then the two cross-cutting rules
+ * it cannot express.
+ *
+ * The schema runs first and short-circuits. A manifest whose shape is wrong
+ * produces cascading nonsense from the reference checks — "binds 'undefined',
+ * which is not a declared read endpoint" when the real answer is "endpoints
+ * must be an array" — so the structural answer is worth giving alone.
+ *
+ * An empty array does not promise the platform will accept it — see the module
+ * note — but a non-empty one is a definite refusal, so this is worth running in
+ * CI and before a publish.
+ *
+ * A declarative plug-in's manifest has no `service` block to name the plug-in, so its
+ * endpoint ids are checked against `publicId` when one is given.
+ */
+export declare function validateManifest(manifest: unknown, options?: {
+    publicId?: string;
+}): ValidationProblem[];
+/** Every `{name}` in a template, in order. */
+export declare function templateNames(value: string): string[];