initiative-plugin-sdk 2.0.0

package/dist/dev.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `initiative-plugin dev --initiative <url> --api-key <key>`: a declarative plug-in
+ * on your own deployment, uploaded again each time its source changes.
+ *
+ * Each pass builds the plug-in, packs its listing file (`pack.ts`) and uploads it
+ * with its picture, as the owner whose personal API key is given: the
+ * deployment publishes it as its own plug-in, on the shelf straight away. The
+ * upload is versioned `<listing version>-dev.<digest of the file>`, since a
+ * deployment publishes each version once; communities that installed the plug-in
+ * move to it from its Update button, or on their own if they follow updates.
+ *
+ * It watches the directory holding the plug-in's definition, and builds again a
+ * moment after the last change there.
+ */
+export interface DevOptions {
+    /** The plug-in's package directory. */
+    root: string;
+    /** The module whose default export is the plug-in's definition, relative to `root`. */
+    plugin: string;
+    /** The deployment's address, such as `https://initiative.example.com`. */
+    initiative: string;
+    /** A personal API key of an account that may configure the deployment. */
+    apiKey: string;
+    /** Stops watching; `dev` then answers 0. */
+    signal?: AbortSignal;
+}
+/** Upload the plug-in, then again on each change. Answers the process's exit code. */
+export declare function dev(options: DevOptions): Promise<number>;

package/dist/dev.js

@@ -0,0 +1,147 @@
+/**
+ * `initiative-plugin dev --initiative <url> --api-key <key>`: a declarative plug-in
+ * on your own deployment, uploaded again each time its source changes.
+ *
+ * Each pass builds the plug-in, packs its listing file (`pack.ts`) and uploads it
+ * with its picture, as the owner whose personal API key is given: the
+ * deployment publishes it as its own plug-in, on the shelf straight away. The
+ * upload is versioned `<listing version>-dev.<digest of the file>`, since a
+ * deployment publishes each version once; communities that installed the plug-in
+ * move to it from its Update button, or on their own if they follow updates.
+ *
+ * It watches the directory holding the plug-in's definition, and builds again a
+ * moment after the last change there.
+ */
+import { createHash } from "node:crypto";
+import { watch } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import { bundler, compile } from "./build.js";
+import { listingFile } from "./pack.js";
+/** How long the source must be still before it is built again, in milliseconds. */
+const SETTLE_MS = 200;
+/** Upload the plug-in, then again on each change. Answers the process's exit code. */
+export async function dev(options) {
+    const esbuild = await bundler("dev");
+    if (!esbuild)
+        return 1;
+    const root = resolve(options.root);
+    const base = options.initiative.replace(/\/+$/, "");
+    let uploaded = "";
+    /** Send one request as the key's owner; null when the deployment could not be reached. */
+    const send = async (path, body) => {
+        try {
+            const response = await fetch(`${base}${path}`, {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${options.apiKey}`,
+                    ...(body instanceof FormData ? {} : { "content-type": "application/json" }),
+                },
+                body: body instanceof FormData ? body : JSON.stringify(body),
+            });
+            return { status: response.status, text: (await response.text()).trim() };
+        }
+        catch (error) {
+            process.stderr.write(`could not reach ${base}: ${error.message}\n`);
+            return null;
+        }
+    };
+    /** A refusal of the key itself ends the run: nothing later would be accepted either. */
+    const refusedKey = (status) => status === 401 || status === 403;
+    /** One pass. Answers an exit code to stop with, or null to keep watching. */
+    const upload = async () => {
+        let packed;
+        try {
+            const compiled = await compile(esbuild, root, options.plugin);
+            if (compiled.problems) {
+                for (const problem of compiled.problems)
+                    process.stderr.write(`${problem}\n`);
+                return null;
+            }
+            if (!compiled.plugin.hosts) {
+                process.stderr.write("dev uploads a declarative plug-in; pack a container plug-in's listing and register its service on the deployment\n");
+                return 1;
+            }
+            packed = listingFile(compiled.plugin, compiled.manifest, root);
+        }
+        catch (error) {
+            process.stderr.write(`${error.message}\n`);
+            return null;
+        }
+        const { listing, avatar } = packed;
+        const digest = createHash("sha256").update(JSON.stringify(listing)).digest("hex").slice(0, 8);
+        const version = `${listing.version}-dev.${digest}`;
+        const name = `${listing.public_id} ${version}`;
+        if (digest === uploaded) {
+            process.stdout.write(`${name} is already uploaded\n`);
+            return null;
+        }
+        if (avatar) {
+            const form = new FormData();
+            form.append("file", new Blob([new Uint8Array(avatar)]), basename(String(listing.avatar_url)));
+            const answer = await send("/api/v1/marketplace/local/media", form);
+            if (!answer)
+                return null;
+            if (answer.status !== 201) {
+                process.stderr.write(`the deployment refused the picture: ${answer.status} ${answer.text}\n`);
+                return refusedKey(answer.status) ? 1 : null;
+            }
+            listing.avatar_url = JSON.parse(answer.text).path;
+        }
+        const answer = await send("/api/v1/marketplace/local/upload", { manifest: { ...listing, version } });
+        if (!answer)
+            return null;
+        if (answer.status !== 201) {
+            process.stderr.write(`the deployment refused ${name}: ${answer.status} ${answer.text}\n`);
+            return refusedKey(answer.status) ? 1 : null;
+        }
+        uploaded = digest;
+        process.stdout.write(`uploaded ${name} (uid ${listing.uid}): ${answer.status} ${answer.text}\n`);
+        return null;
+    };
+    const first = await upload();
+    if (first !== null)
+        return first;
+    if (options.signal?.aborted)
+        return 0;
+    const source = dirname(resolve(root, options.plugin));
+    process.stdout.write(`watching ${relative(process.cwd(), source) || "."} for changes\n`);
+    return new Promise((done) => {
+        const watcher = watch(source, { recursive: true });
+        let timer;
+        let running = false;
+        let changed = false;
+        const finish = (code) => {
+            clearTimeout(timer);
+            watcher.close();
+            options.signal?.removeEventListener("abort", stop);
+            done(code);
+        };
+        const stop = () => finish(0);
+        const settle = () => {
+            clearTimeout(timer);
+            timer = setTimeout(pass, SETTLE_MS);
+        };
+        const pass = async () => {
+            if (running) {
+                changed = true;
+                return;
+            }
+            running = true;
+            const code = await upload();
+            running = false;
+            if (code !== null)
+                finish(code);
+            else if (changed) {
+                changed = false;
+                settle();
+            }
+        };
+        watcher.on("change", settle);
+        watcher.on("error", (error) => {
+            process.stderr.write(`stopped watching ${source}: ${error.message}\n`);
+            finish(1);
+        });
+        options.signal?.addEventListener("abort", stop);
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/dev.js.map

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

package/dist/expression.d.ts

@@ -0,0 +1,28 @@
+/**
+ * JSONata, as Initiative evaluates a declarative plug-in's expressions.
+ *
+ * Standard JSONata, the reference implementation, with no functions added.
+ * Every evaluation is bounded by three of the contract's caps, which
+ * Initiative reads from the same contract: `expressionTimeMs`,
+ * `expressionDepth` (levels of nesting, function calls included) and
+ * `expressionOutputBytes` (the answer, as JSON). Passing one is a failure,
+ * as an expression that raises an error is.
+ */
+import jsonata from "jsonata";
+/** An expression that does not parse, failed, or passed one of its bounds. */
+export declare class ExpressionError extends Error {
+    /** Where in the expression, in characters, when the failure names a place. */
+    readonly position: number | undefined;
+    constructor(message: string, position?: number);
+}
+/** An expression's syntax tree. Throws {@link ExpressionError} when it does not parse. */
+export declare function parseExpression(text: string): jsonata.ExprNode;
+/**
+ * Evaluate one expression over `input`, within the contract's bounds. The
+ * answer comes back as plain JSON, or undefined when the expression answers
+ * nothing. `now` fixes what `$now()` and `$millis()` answer; absent, they
+ * answer the moment of evaluation.
+ */
+export declare function evaluate(text: string, input: unknown, options?: {
+    now?: Date | string | number;
+}): Promise<unknown>;

package/dist/expression.js

@@ -0,0 +1,67 @@
+/**
+ * JSONata, as Initiative evaluates a declarative plug-in's expressions.
+ *
+ * Standard JSONata, the reference implementation, with no functions added.
+ * Every evaluation is bounded by three of the contract's caps, which
+ * Initiative reads from the same contract: `expressionTimeMs`,
+ * `expressionDepth` (levels of nesting, function calls included) and
+ * `expressionOutputBytes` (the answer, as JSON). Passing one is a failure,
+ * as an expression that raises an error is.
+ */
+import jsonata from "jsonata";
+import { CAPS } from "./contract.js";
+/** An expression that does not parse, failed, or passed one of its bounds. */
+export class ExpressionError extends Error {
+    /** Where in the expression, in characters, when the failure names a place. */
+    position;
+    constructor(message, position) {
+        super(message);
+        this.name = "ExpressionError";
+        this.position = position;
+    }
+}
+function failure(error) {
+    const { message, position } = (error ?? {});
+    return new ExpressionError(typeof message === "string" ? message : String(error), typeof position === "number" ? position : undefined);
+}
+/** An expression's syntax tree. Throws {@link ExpressionError} when it does not parse. */
+export function parseExpression(text) {
+    try {
+        return jsonata(text).ast();
+    }
+    catch (error) {
+        throw failure(error);
+    }
+}
+/** `$now()` and `$millis()` answering one instant, as every expression of one call sees it. */
+async function clock(millis) {
+    return {
+        now: await jsonata(`function($picture, $timezone) { $fromMillis(${millis}, $picture, $timezone) }`).evaluate({}),
+        millis: await jsonata(`function() { ${millis} }`).evaluate({}),
+    };
+}
+/**
+ * Evaluate one expression over `input`, within the contract's bounds. The
+ * answer comes back as plain JSON, or undefined when the expression answers
+ * nothing. `now` fixes what `$now()` and `$millis()` answer; absent, they
+ * answer the moment of evaluation.
+ */
+export async function evaluate(text, input, options = {}) {
+    let answer;
+    try {
+        const expression = jsonata(text, { timeout: CAPS.expressionTimeMs, stack: CAPS.expressionDepth });
+        const bindings = options.now === undefined ? undefined : await clock(new Date(options.now).getTime());
+        answer = await expression.evaluate(input, bindings);
+    }
+    catch (error) {
+        throw failure(error);
+    }
+    const json = answer === undefined ? undefined : JSON.stringify(answer);
+    if (json === undefined)
+        return undefined;
+    if (Buffer.byteLength(json, "utf-8") > CAPS.expressionOutputBytes) {
+        throw new ExpressionError(`the answer is over ${CAPS.expressionOutputBytes} bytes`);
+    }
+    return JSON.parse(json);
+}
+//# sourceMappingURL=expression.js.map

package/dist/expression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expression.js","sourceRoot":"","sources":["../src/expression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,8EAA8E;AAC9E,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACxC,8EAA8E;IACrE,QAAQ,CAAqB;IAEtC,YAAY,OAAe,EAAE,QAAiB;QAC5C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,SAAS,OAAO,CAAC,KAAc;IAC7B,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,IAAI,EAAE,CAA8C,CAAC;IACzF,OAAO,IAAI,eAAe,CACxB,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EACrD,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CACpD,CAAC;AACJ,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC7B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,+FAA+F;AAC/F,KAAK,UAAU,KAAK,CAAC,MAAc;IACjC,OAAO;QACL,GAAG,EAAE,MAAM,OAAO,CAAC,+CAA+C,MAAM,0BAA0B,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChH,MAAM,EAAE,MAAM,OAAO,CAAC,gBAAgB,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,IAAY,EACZ,KAAc,EACd,OAAO,GAAqC,EAAE;IAE9C,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC;QAClG,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACtG,MAAM,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACvE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAClE,MAAM,IAAI,eAAe,CAAC,sBAAsB,IAAI,CAAC,qBAAqB,QAAQ,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `initiative-plugin init [dir] [--example minimal]`: a new plug-in, copied from one
+ * of the SDK's examples, with a uid of its own and its package named after its
+ * directory.
+ */
+/** A fresh catalog uid, in Crockford base32. Mint once, write it into the plug-in, never change it. */
+export declare function mintUid(): string;
+export interface InitOptions {
+    /** The new plug-in's directory: absent or empty. */
+    dir: string;
+    example: string;
+}
+/** Copy the example. Answers the process's exit code. */
+export declare function init(options: InitOptions): number;

package/dist/init.js

@@ -0,0 +1,52 @@
+/**
+ * `initiative-plugin init [dir] [--example minimal]`: a new plug-in, copied from one
+ * of the SDK's examples, with a uid of its own and its package named after its
+ * directory.
+ */
+import { randomInt } from "node:crypto";
+import { cpSync, existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CAPS, CHARSETS } from "./contract.js";
+/** Where the examples ship, beside `dist` in the package and `src` in the repo. */
+const EXAMPLES = fileURLToPath(new URL("../examples/", import.meta.url));
+/** A fresh catalog uid, in Crockford base32. Mint once, write it into the plug-in, never change it. */
+export function mintUid() {
+    let uid = "";
+    for (let index = 0; index < CAPS.uidLength; index += 1)
+        uid += CHARSETS.uid[randomInt(CHARSETS.uid.length)];
+    return uid;
+}
+/** Copy the example. Answers the process's exit code. */
+export function init(options) {
+    const examples = readdirSync(EXAMPLES);
+    if (!examples.includes(options.example)) {
+        process.stderr.write(`there is no example ${options.example}; there is ${examples.join(", ")}\n`);
+        return 2;
+    }
+    const dir = resolve(options.dir);
+    if (existsSync(dir) && readdirSync(dir).length > 0) {
+        process.stderr.write(`${dir} is not empty; choose a new directory\n`);
+        return 1;
+    }
+    cpSync(join(EXAMPLES, options.example), dir, {
+        recursive: true,
+        filter: (path) => !/[\\/]node_modules$/.test(path),
+    });
+    const uid = mintUid();
+    const pluginPath = join(dir, "src", "plugin.ts");
+    writeFileSync(pluginPath, readFileSync(pluginPath, "utf-8").replace(/uid: "[0-9A-Z]+"/, `uid: "${uid}"`));
+    const packagePath = join(dir, "package.json");
+    const manifest = JSON.parse(readFileSync(packagePath, "utf-8"));
+    // npm's rule for a package name: lowercase, and no character a URL would escape.
+    const name = basename(dir).toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[._-]+/, "") || "plugin";
+    writeFileSync(packagePath, `${JSON.stringify({ ...manifest, name }, null, 2)}\n`);
+    const where = relative(process.cwd(), dir) || ".";
+    process.stdout.write([
+        `created ${where} from the ${options.example} example, uid ${uid}`,
+        `next: cd ${where} && npm install && npm test`,
+        "",
+    ].join("\n"));
+    return 0;
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

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

package/dist/keys.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Your plug-in's signing keys.
+ *
+ * A plug-in proves who it is to Initiative by signing a short JWT with its own
+ * private key (`private_key_jwt`, RFC 7523). The deployment's operator
+ * registers the matching public keys — a JWKS — against your plug-in's public id,
+ * and the private key never leaves your plug-in.
+ *
+ * Two algorithms are supported, and the deployment picks the one to check by
+ * the registered key's type: `RS256` for an RSA key, `ES256` for a P-256 key.
+ *
+ * Every key carries a `kid`. Each JWT names the `kid` it was signed with, so
+ * rotating is: generate a new key, have the operator register a JWKS holding
+ * both public keys, switch your plug-in to the new one, then drop the old entry.
+ */
+import { type KeyObject } from "node:crypto";
+/** The algorithms a plug-in key may use. */
+export type PluginKeyAlgorithm = "RS256" | "ES256";
+/** One public key, as a JWK. */
+export interface PublicJwk {
+    kty: "RSA" | "EC";
+    kid: string;
+    alg: PluginKeyAlgorithm;
+    use: "sig";
+    n?: string;
+    e?: string;
+    crv?: "P-256";
+    x?: string;
+    y?: string;
+}
+/** A JSON Web Key Set: what the operator registers for your plug-in. */
+export interface Jwks {
+    keys: PublicJwk[];
+}
+/** A private key ready to sign with. */
+export interface PluginSigningKey {
+    key: KeyObject;
+    kid: string;
+    alg: PluginKeyAlgorithm;
+}
+/** What {@link generatePluginKeys} returns. */
+export interface GeneratedPluginKeys {
+    /** PKCS#8 PEM. Keep it secret, and out of source control. */
+    privateKeyPem: string;
+    /** The public half, to register with the deployment. */
+    jwks: Jwks;
+    kid: string;
+    alg: PluginKeyAlgorithm;
+}
+/**
+ * Generate a new signing key.
+ *
+ * `kid` defaults to the key's RFC 7638 thumbprint, so the same key always gets
+ * the same id and two keys never share one.
+ */
+export declare function generatePluginKeys(options?: {
+    alg?: PluginKeyAlgorithm;
+    kid?: string;
+}): GeneratedPluginKeys;
+/**
+ * Load a PEM private key for signing, under the `kid` it was registered with,
+ * or its RFC 7638 thumbprint when none is given.
+ *
+ * The algorithm follows from the key: an RSA key signs `RS256`, a P-256 key
+ * signs `ES256`, and any other key is refused.
+ */
+export declare function loadPrivateKey(pem: string, kid?: string): PluginSigningKey;
+/** The JWKS for one signing key: its public half, with its `kid`. */
+export declare function publicJwks(signing: PluginSigningKey): Jwks;
+/** The algorithm a key signs with, from its type. */
+export declare function algorithmOf(key: KeyObject): PluginKeyAlgorithm;
+/**
+ * Sign a compact JWT with a plug-in key. `typ` goes in the header; a plug-in's own
+ * assertions are plain `JWT`.
+ *
+ * ES256 signatures are written in the JOSE form (`r || s`, 64 bytes), which is
+ * what `ieee-p1363` produces.
+ */
+export declare function signJwt(signing: PluginSigningKey, claims: Record<string, unknown>, typ?: string): string;
+/**
+ * A public key's fingerprint: its RFC 7638 SHA-256 thumbprint, base64url
+ * without padding. The plug-in logs it at start, and Initiative shows the same
+ * value for the key it reads from the plug-in.
+ */
+export declare function jwkThumbprint(jwk: PublicJwk): string;

package/dist/keys.js

@@ -0,0 +1,109 @@
+/**
+ * Your plug-in's signing keys.
+ *
+ * A plug-in proves who it is to Initiative by signing a short JWT with its own
+ * private key (`private_key_jwt`, RFC 7523). The deployment's operator
+ * registers the matching public keys — a JWKS — against your plug-in's public id,
+ * and the private key never leaves your plug-in.
+ *
+ * Two algorithms are supported, and the deployment picks the one to check by
+ * the registered key's type: `RS256` for an RSA key, `ES256` for a P-256 key.
+ *
+ * Every key carries a `kid`. Each JWT names the `kid` it was signed with, so
+ * rotating is: generate a new key, have the operator register a JWKS holding
+ * both public keys, switch your plug-in to the new one, then drop the old entry.
+ */
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign as cryptoSign, } from "node:crypto";
+/**
+ * Generate a new signing key.
+ *
+ * `kid` defaults to the key's RFC 7638 thumbprint, so the same key always gets
+ * the same id and two keys never share one.
+ */
+export function generatePluginKeys(options = {}) {
+    const alg = options.alg ?? "RS256";
+    const { privateKey } = alg === "RS256"
+        ? generateKeyPairSync("rsa", { modulusLength: 2048 })
+        : alg === "ES256"
+            ? generateKeyPairSync("ec", { namedCurve: "P-256" })
+            : unsupported(alg);
+    const kid = options.kid ?? thumbprint(privateKey);
+    return {
+        privateKeyPem: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+        jwks: publicJwks({ key: privateKey, kid, alg }),
+        kid,
+        alg,
+    };
+}
+/**
+ * Load a PEM private key for signing, under the `kid` it was registered with,
+ * or its RFC 7638 thumbprint when none is given.
+ *
+ * The algorithm follows from the key: an RSA key signs `RS256`, a P-256 key
+ * signs `ES256`, and any other key is refused.
+ */
+export function loadPrivateKey(pem, kid) {
+    const key = createPrivateKey(pem);
+    return { key, kid: kid || thumbprint(key), alg: algorithmOf(key) };
+}
+/** The JWKS for one signing key: its public half, with its `kid`. */
+export function publicJwks(signing) {
+    const jwk = createPublicKey(signing.key).export({ format: "jwk" });
+    const entry = signing.alg === "RS256"
+        ? { kty: "RSA", kid: signing.kid, alg: "RS256", use: "sig", n: jwk.n, e: jwk.e }
+        : {
+            kty: "EC",
+            kid: signing.kid,
+            alg: "ES256",
+            use: "sig",
+            crv: "P-256",
+            x: jwk.x,
+            y: jwk.y,
+        };
+    return { keys: [entry] };
+}
+/** The algorithm a key signs with, from its type. */
+export function algorithmOf(key) {
+    if (key.asymmetricKeyType === "rsa")
+        return "RS256";
+    if (key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === "prime256v1") {
+        return "ES256";
+    }
+    throw new TypeError(`unsupported key type ${key.asymmetricKeyType ?? "unknown"}: use an RSA or P-256 key`);
+}
+/**
+ * Sign a compact JWT with a plug-in key. `typ` goes in the header; a plug-in's own
+ * assertions are plain `JWT`.
+ *
+ * ES256 signatures are written in the JOSE form (`r || s`, 64 bytes), which is
+ * what `ieee-p1363` produces.
+ */
+export function signJwt(signing, claims, typ = "JWT") {
+    const header = { alg: signing.alg, kid: signing.kid, typ };
+    const input = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(claims))}`;
+    const signature = signing.alg === "ES256"
+        ? cryptoSign("sha256", Buffer.from(input), { key: signing.key, dsaEncoding: "ieee-p1363" })
+        : cryptoSign("sha256", Buffer.from(input), signing.key);
+    return `${input}.${signature.toString("base64url")}`;
+}
+function base64url(text) {
+    return Buffer.from(text, "utf-8").toString("base64url");
+}
+/**
+ * A public key's fingerprint: its RFC 7638 SHA-256 thumbprint, base64url
+ * without padding. The plug-in logs it at start, and Initiative shows the same
+ * value for the key it reads from the plug-in.
+ */
+export function jwkThumbprint(jwk) {
+    const members = jwk.kty === "RSA"
+        ? { e: jwk.e, kty: jwk.kty, n: jwk.n }
+        : { crv: jwk.crv, kty: jwk.kty, x: jwk.x, y: jwk.y };
+    return createHash("sha256").update(JSON.stringify(members)).digest("base64url");
+}
+function thumbprint(privateKey) {
+    return jwkThumbprint(createPublicKey(privateKey).export({ format: "jwk" }));
+}
+function unsupported(alg) {
+    throw new TypeError(`unsupported algorithm ${alg}: use RS256 or ES256`);
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

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

package/dist/manifest.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `initiative-plugin-sdk/manifest`: the contract as types, the plug-in's one
+ * definition, and checking a manifest before a deployment does.
+ */
+export * from "./contract.js";
+export { definePlugin, defineEndpoint, type Actor, type AfterConnectAnswer, type AfterConnectCall, type PluginContext, type PluginDefinition, type Call, type CallableEndpoint, type DashboardDeclaration, type EmittedEndpoint, type EndpointCall, type EndpointDeclaration, type Handoff, type Hooks, type ListingDeclaration, type Outcome, type Params, type ParamSpec, type ParamValue, type Result, type ReturnSpec, type RevokeCall, type ScheduleCall, type ScheduleDeclaration, type SurfaceCall, type SurfaceDeclaration, type WebhookCall, type WidgetDeclaration, } from "./define.js";
+export { MANIFEST_PATH, manifestSchema, validateDocument, validateManifest, type PluginDocument, type ValidationProblem, } from "./validate.js";
+export type { Jwks, PublicJwk } from "./keys.js";

package/dist/manifest.js

@@ -0,0 +1,8 @@
+/**
+ * `initiative-plugin-sdk/manifest`: the contract as types, the plug-in's one
+ * definition, and checking a manifest before a deployment does.
+ */
+export * from "./contract.js";
+export { definePlugin, defineEndpoint, } from "./define.js";
+export { MANIFEST_PATH, manifestSchema, validateDocument, validateManifest, } from "./validate.js";
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,eAAe,CAAC;AAE9B,OAAO,EACL,YAAY,EACZ,cAAc,GA4Bf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,eAAe,CAAC"}

package/dist/pack.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `initiative-plugin pack`: the plug-in as one listing file, the file a self-hosted
+ * deployment publishes as its own plug-in.
+ *
+ * The listing file is the shape a deployment's listing upload
+ * (`POST /api/v1/marketplace/local/upload`, as `{"manifest": <file>}`) and its
+ * catalog directory (`MARKETPLACE_EXTRA_CATALOG_DIR`) read: what the catalogue
+ * shows, this version's manifest as its `definition`, and its registration.
+ * The manifest is the one `build` makes, checked the same way.
+ *
+ * The listing's picture is named by the path the deployment keeps it under,
+ * which is the SHA-256 of its bytes, so it is uploaded beside the file
+ * (`POST /api/v1/marketplace/local/media`). A deployment keeps PNG, JPEG, GIF
+ * and WebP; any other picture is left out, and the listing shows the
+ * deployment's default mark.
+ */
+import type { Manifest } from "./contract.js";
+import type { AnyPlugin } from "./define.js";
+export interface PackOptions {
+    /** The plug-in's package directory. */
+    root: string;
+    /** The module whose default export is the plug-in's definition, relative to `root`. */
+    plugin: string;
+    /** Where to write the listing file, relative to `root`. Default: `<publicId>-<version>.json`. */
+    out?: string;
+}
+/** The listing file, and the picture to upload beside it (null when it names none). */
+export interface Packed {
+    listing: Record<string, unknown>;
+    avatar: Buffer | null;
+}
+/** The listing file for a plug-in whose manifest `compile` made. */
+export declare function listingFile(plugin: AnyPlugin, manifest: Manifest, root: string): Packed;
+/** Write the plug-in's listing file. Answers the process's exit code. */
+export declare function pack(options: PackOptions): Promise<number>;