@messh/sdk 0.0.0-stage → 0.1.0

package/dist/keys.js

@@ -0,0 +1,198 @@
+// Key sources. Keys are used locally; they never go to messh.
+import { createHash, createPrivateKey, createPublicKey, sign as edSign } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { connect } from "node:net";
+import { homedir } from "node:os";
+import { MesshError } from "./errors.js";
+import { sshString } from "./wba.js";
+const PKCS8_ED25519_PREFIX = Buffer.from("302e020100300506032b657004220420", "hex");
+class LocalSigner {
+    #key;
+    #pub;
+    constructor(key) {
+        if (key.asymmetricKeyType !== "ed25519")
+            throw new MesshError("invalid_key", "need an Ed25519 key");
+        this.#key = key;
+        const der = createPublicKey(key).export({ format: "der", type: "spki" });
+        this.#pub = new Uint8Array(der.subarray(der.length - 32));
+    }
+    publicKey() { return this.#pub; }
+    sign(data) { return new Uint8Array(edSign(null, data, this.#key)); }
+    toJSON() { return "messh.Signer(ed25519)"; }
+}
+function fromSeed(seed) {
+    if (seed.length !== 32)
+        throw new MesshError("invalid_key", "seed must be 32 bytes");
+    return new LocalSigner(createPrivateKey({ key: Buffer.concat([PKCS8_ED25519_PREFIX, seed]), format: "der", type: "pkcs8" }));
+}
+/** Unpack the openssh-key-v1 container (PROTOCOL.key) to the Ed25519 seed. */
+function fromOpenSSH(pem) {
+    const buf = Buffer.from(pem.replace(/-----[^-]+-----/g, "").replace(/\s+/g, ""), "base64");
+    const magic = "openssh-key-v1\0";
+    if (buf.subarray(0, magic.length).toString("latin1") !== magic)
+        throw new MesshError("invalid_key", "not an OpenSSH private key");
+    let off = magic.length;
+    const take = (b, o) => {
+        if (o + 4 > b.length)
+            throw new MesshError("invalid_key", "truncated OpenSSH key");
+        const n = b.readUInt32BE(o);
+        if (o + 4 + n > b.length)
+            throw new MesshError("invalid_key", "truncated OpenSSH key");
+        return [b.subarray(o + 4, o + 4 + n), o + 4 + n];
+    };
+    let cipher;
+    [cipher, off] = take(buf, off);
+    if (cipher.toString() !== "none")
+        throw new MesshError("invalid_key", "passphrase-protected key; load it into ssh-agent (ssh-add) and use sshAgent()");
+    [, off] = take(buf, off);
+    [, off] = take(buf, off);
+    if (buf.readUInt32BE(off) !== 1)
+        throw new MesshError("invalid_key", "expected one key");
+    off += 4;
+    [, off] = take(buf, off);
+    const [priv] = take(buf, off);
+    if (priv.readUInt32BE(0) !== priv.readUInt32BE(4))
+        throw new MesshError("invalid_key", "OpenSSH check bytes differ");
+    let p = 8, type, pub, sk;
+    [type, p] = take(priv, p);
+    if (type.toString() !== "ssh-ed25519")
+        throw new MesshError("invalid_key", `need an ssh-ed25519 key, got ${type}`);
+    [pub, p] = take(priv, p);
+    [sk, p] = take(priv, p);
+    if (sk.length !== 64 || !sk.subarray(32).equals(pub))
+        throw new MesshError("invalid_key", "malformed ssh-ed25519 private key");
+    return fromSeed(sk.subarray(0, 32));
+}
+function parse(data) {
+    const text = data.toString("utf8");
+    if (text.includes("OPENSSH PRIVATE KEY"))
+        return fromOpenSSH(text);
+    if (text.includes("ENCRYPTED PRIVATE KEY"))
+        throw new MesshError("invalid_key", "encrypted keys aren't supported; load the key into ssh-agent and use sshAgent()");
+    try {
+        return new LocalSigner(text.includes("-----BEGIN") ? createPrivateKey(text) : createPrivateKey({ key: data, format: "der", type: "pkcs8" }));
+    }
+    catch (e) {
+        if (e instanceof MesshError)
+            throw e;
+        throw new MesshError("invalid_key", e.message);
+    }
+}
+/** Unencrypted ssh-ed25519 OpenSSH key or PKCS#8 PEM, e.g. ~/.ssh/id_ed25519. */
+export function keyFile(path) {
+    return async () => {
+        const p = path.startsWith("~/") ? homedir() + path.slice(1) : path;
+        let data;
+        try {
+            data = await readFile(p);
+        }
+        catch (e) {
+            const hint = e.code === "ENOENT" ? "; create one with ssh-keygen -t ed25519, then messh publish" : "";
+            throw new MesshError("invalid_key", `read ${path}: ${e.message}${hint}`);
+        }
+        return parse(data);
+    };
+}
+/**
+ * A key held by ssh-agent, such as a passphrase-protected key you added with
+ * ssh-add. The private key stays in the agent. With several Ed25519 keys
+ * loaded, pass the fingerprint (SHA256:…) of the one you published.
+ */
+export function sshAgent(options = {}) {
+    return async () => {
+        const path = options.socket ?? process.env.SSH_AUTH_SOCK ?? (process.platform === "win32" ? "\\\\.\\pipe\\openssh-ssh-agent" : "");
+        if (!path)
+            throw new MesshError("invalid_key", 'ssh-agent isn\'t running (SSH_AUTH_SOCK is not set); start it: eval "$(ssh-agent)" && ssh-add');
+        const reply = await agentCall(path, Buffer.from([AGENTC_REQUEST_IDENTITIES]));
+        if (reply[0] !== AGENT_IDENTITIES_ANSWER)
+            throw new MesshError("invalid_key", "ssh-agent wouldn't list its keys");
+        const keys = [];
+        let off = 5;
+        for (let i = reply.readUInt32BE(1); i > 0; i--) {
+            const [blob, o1] = take(reply, off);
+            [, off] = take(reply, o1); // comment
+            const [type, o2] = take(blob, 0);
+            if (type.toString() !== "ssh-ed25519")
+                continue;
+            const [pub] = take(blob, o2);
+            keys.push({ blob, pub, fingerprint: "SHA256:" + createHash("sha256").update(blob).digest("base64").replace(/=+$/, "") });
+        }
+        const list = keys.map((k) => k.fingerprint).join(", ");
+        if (!keys.length)
+            throw new MesshError("invalid_key", "ssh-agent has no Ed25519 keys; add yours with ssh-add ~/.ssh/id_ed25519");
+        const pick = options.fingerprint ? keys.filter((k) => k.fingerprint === options.fingerprint) : keys;
+        if (!pick.length)
+            throw new MesshError("invalid_key", `ssh-agent has no key ${options.fingerprint}; it has ${list}`);
+        if (pick.length > 1)
+            throw new MesshError("invalid_key", `ssh-agent has ${keys.length} Ed25519 keys; choose one with sshAgent({ fingerprint }): ${list}`);
+        return new AgentSigner(path, pick[0].blob, new Uint8Array(pick[0].pub));
+    };
+}
+// ssh-agent protocol (draft-miller-ssh-agent): uint32 length, message type, payload.
+const AGENTC_REQUEST_IDENTITIES = 11, AGENT_IDENTITIES_ANSWER = 12, AGENTC_SIGN_REQUEST = 13, AGENT_SIGN_RESPONSE = 14;
+class AgentSigner {
+    path;
+    blob;
+    pub;
+    constructor(path, blob, pub) {
+        this.path = path;
+        this.blob = blob;
+        this.pub = pub;
+    }
+    publicKey() { return this.pub; }
+    async sign(data) {
+        const flags = Buffer.alloc(4);
+        const reply = await agentCall(this.path, Buffer.concat([Buffer.from([AGENTC_SIGN_REQUEST]), sshString(this.blob), sshString(data), flags]));
+        if (reply[0] !== AGENT_SIGN_RESPONSE)
+            throw new Error("ssh-agent refused to sign; is the key still loaded (ssh-add -l)?");
+        const [sigBlob] = take(reply, 1);
+        const [type, o] = take(sigBlob, 0);
+        const [sig] = take(sigBlob, o);
+        if (type.toString() !== "ssh-ed25519" || sig.length !== 64)
+            throw new Error("ssh-agent returned an unexpected signature");
+        return new Uint8Array(sig);
+    }
+    toJSON() { return "messh.Signer(ssh-agent)"; }
+}
+function take(b, o) {
+    if (o + 4 > b.length || o + 4 + b.readUInt32BE(o) > b.length)
+        throw new MesshError("invalid_key", "malformed ssh-agent reply");
+    const n = b.readUInt32BE(o);
+    return [b.subarray(o + 4, o + 4 + n), o + 4 + n];
+}
+function agentCall(path, msg) {
+    return new Promise((resolve, reject) => {
+        const sock = connect(path);
+        let buf = Buffer.alloc(0);
+        sock.setTimeout(30_000, () => sock.destroy(new Error("ssh-agent timed out")));
+        sock.on("connect", () => sock.write(sshString(msg)));
+        sock.on("data", (d) => {
+            buf = Buffer.concat([buf, d]);
+            if (buf.length >= 4 && buf.length >= 4 + buf.readUInt32BE(0)) {
+                sock.end();
+                resolve(buf.subarray(4, 4 + buf.readUInt32BE(0)));
+            }
+        });
+        sock.on("error", (e) => reject(new MesshError("invalid_key", `ssh-agent at ${path}: ${e.message}`)));
+        sock.on("close", () => reject(new MesshError("invalid_key", `ssh-agent at ${path} closed the connection`)));
+    });
+}
+/** Key in an environment variable: PEM text, or base64 of PEM or PKCS#8 DER. */
+export function keyEnv(name) {
+    return async () => {
+        const v = (process.env[name] ?? "").trim();
+        if (!v)
+            throw new MesshError("invalid_key", `environment variable ${name} is empty`);
+        return parse(v.includes("-----BEGIN") ? Buffer.from(v) : Buffer.from(v, "base64"));
+    };
+}
+/** Raw 32-byte Ed25519 seed. */
+export function keySeed(seed) {
+    return async () => fromSeed(seed);
+}
+export async function resolveKey(source) {
+    const signer = typeof source === "function" ? await source() : source;
+    if ((await signer.publicKey()).length !== 32)
+        throw new MesshError("invalid_key", "signer has no Ed25519 public key");
+    return signer;
+}

package/dist/verify.d.ts

@@ -0,0 +1,116 @@
+import * as wba from "./wba.js";
+export { VerifyError } from "./errors.js";
+export declare const ACCEPT_SIGNATURE = "sig1=(\"@method\" \"@authority\" \"@path\" \"signature-agent\");keyid;created;expires;nonce;alg=\"ed25519\";tag=\"web-bot-auth\"";
+/** Default limit on request bodies the middleware reads (bytes). */
+export declare const MAX_BODY_BYTES: number;
+/** A verified caller. */
+export interface Agent {
+    /** messh username, e.g. "mukul". */
+    identity: string;
+    /** Key name on messh, e.g. "laptop". */
+    keyName: string;
+    /** RFC 7638 thumbprint. */
+    keyId: string;
+    /** SHA256:… of the SSH key. */
+    fingerprint: string;
+    /** Signature-Agent. */
+    agentUrl: string;
+    /** Signature creation time, seconds since epoch. */
+    created: number;
+}
+/** Replay store. add() returns false if key was seen within ttlSeconds. */
+export interface NonceStore {
+    add(key: string, ttlSeconds: number): boolean | Promise<boolean>;
+}
+export declare class MemoryNonceStore implements NonceStore {
+    #private;
+    add(key: string, ttlSeconds: number): boolean;
+}
+export interface VerifierOptions {
+    /** Who may call: messh usernames, or "*". Required. */
+    trust: string[];
+    /** Accepted registry origins (default ["https://messh.io"]), or origin → fetch base URL. */
+    registries?: string[] | Record<string, string>;
+    /** Max |now − created| in seconds. Default 60. */
+    maxSkew?: number;
+    /** Key directory cache in seconds. Default 300. */
+    cacheTtl?: number;
+    /** Keep cached keys this long if messh is unreachable. Default 3600. */
+    staleIfError?: number;
+    /** Replay store. Default in memory. */
+    nonceStore?: NonceStore;
+    /** Directory fetch timeout. Default 5000 ms. */
+    timeoutMs?: number;
+    /** Largest request body messhAuth and verifyRequest read; bigger ones get 413 body_too_large. Default 1 MiB. */
+    maxBodyBytes?: number;
+    /** Seconds since epoch (tests). */
+    clock?: () => number;
+    /** Fixed directory or resolver (tests, air-gapped setups). */
+    directory?: wba.Directory | ((agentUrl: string, identity: string) => Promise<wba.Directory>);
+}
+export interface VerifyInput {
+    method: string;
+    /** Full request URL. */
+    url: string | URL;
+    headers: Headers | Record<string, string | string[] | undefined>;
+    body?: Uint8Array | string | null;
+}
+export declare class Verifier {
+    readonly trust: string[];
+    readonly maxBodyBytes: number;
+    private readonly registries;
+    private readonly maxSkew;
+    private readonly cacheTtl;
+    private readonly staleIfError;
+    private readonly nonces;
+    private readonly timeoutMs;
+    private readonly clock;
+    private readonly directory?;
+    private readonly cache;
+    private readonly inflight;
+    constructor(options: VerifierOptions);
+    /** Verify one request; throws VerifyError. */
+    verify(input: VerifyInput): Promise<Agent>;
+    /** Verify a fetch Request (Workers, Hono, Next.js route handlers, Deno, Bun). */
+    verifyRequest(request: Request): Promise<Agent>;
+    private identityOf;
+    /**
+     * The signer's key for kid. Directories are cached for cacheTtl; an unknown
+     * kid refetches at most every MIN_REFRESH s (so a key published a moment ago
+     * works), unknown identities are remembered the same way, one fetch per
+     * directory runs at a time, and while messh is unreachable cached keys keep
+     * working for staleIfError.
+     */
+    private lookup;
+    /** Fetch a directory: the directory, null for no such identity, undefined if messh couldn't answer. One request per URL at a time. */
+    private fetchOnce;
+    private store;
+}
+/** Create a verifier (reuse it; it caches keys). */
+export declare function createVerifier(options: VerifierOptions): Verifier;
+type Req = {
+    method: string;
+    originalUrl?: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    protocol?: string;
+    on: Function;
+    body?: unknown;
+    rawBody?: Buffer;
+    agent?: Agent;
+    _body?: boolean;
+};
+type Res = {
+    status(code: number): Res;
+    setHeader(k: string, v: string): void;
+    json(body: unknown): void;
+};
+/**
+ * Express / Connect middleware. Mount it before express.json(): it reads
+ * the raw body, verifies, then sets req.rawBody, req.agent and (for JSON)
+ * req.body. Set `trustProxy` if TLS ends at a proxy (uses X-Forwarded-Proto).
+ */
+export declare function messhAuth(options: VerifierOptions & {
+    verifier?: Verifier;
+    trustProxy?: boolean;
+}): (req: Req, res: Res, next: (err?: unknown) => void) => void;

package/dist/verify.js

@@ -0,0 +1,333 @@
+// @messh/sdk/verify: verify Web Bot Auth signatures with keys from messh.
+import { createPublicKey, verify as edVerify } from "node:crypto";
+import * as wba from "./wba.js";
+import { VerifyError } from "./errors.js";
+import { VERSION } from "./index.js";
+export { VerifyError } from "./errors.js";
+export const ACCEPT_SIGNATURE = 'sig1=("@method" "@authority" "@path" "signature-agent");keyid;created;expires;nonce;alg="ed25519";tag="web-bot-auth"';
+const IDENTITY = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
+const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+// Directory cache policy, the same in every messh SDK.
+/** An unknown keyid refetches its signer's directory at most this often (s), so new keys work within seconds. */
+const MIN_REFRESH = 30;
+/** While messh is unreachable, retry a directory at most this often (s). */
+const RETRY_AFTER = 5;
+/** Directories kept at most. */
+const MAX_ENTRIES = 10_000;
+/** Default limit on request bodies the middleware reads (bytes). */
+export const MAX_BODY_BYTES = 1 << 20;
+export class MemoryNonceStore {
+    #seen = new Map();
+    add(key, ttlSeconds) {
+        const now = Date.now();
+        for (const [k, exp] of this.#seen)
+            if (exp < now)
+                this.#seen.delete(k);
+        if (this.#seen.has(key))
+            return false;
+        this.#seen.set(key, now + ttlSeconds * 1000);
+        return true;
+    }
+}
+const fail = (code, msg, status = 401) => new VerifyError(code, msg, status);
+export class Verifier {
+    trust;
+    maxBodyBytes;
+    registries;
+    maxSkew;
+    cacheTtl;
+    staleIfError;
+    nonces;
+    timeoutMs;
+    clock;
+    directory;
+    cache = new Map();
+    inflight = new Map();
+    constructor(options) {
+        if (!options?.trust?.length)
+            throw new TypeError('trust is required, e.g. { trust: ["mukul"] } or ["*"]');
+        this.trust = [...options.trust];
+        const regs = options.registries ?? ["https://messh.io"];
+        const pairs = Array.isArray(regs) ? regs.map((r) => [r, r]) : Object.entries(regs);
+        this.registries = new Map(pairs.map(([o, b]) => [o.replace(/\/+$/, ""), b.replace(/\/+$/, "")]));
+        this.maxSkew = options.maxSkew ?? 60;
+        this.cacheTtl = options.cacheTtl ?? 300;
+        this.staleIfError = options.staleIfError ?? 3600;
+        this.nonces = options.nonceStore ?? new MemoryNonceStore();
+        this.timeoutMs = options.timeoutMs ?? 5000;
+        this.maxBodyBytes = options.maxBodyBytes ?? MAX_BODY_BYTES;
+        this.clock = options.clock ?? (() => Date.now() / 1000);
+        this.directory = options.directory;
+    }
+    /** Verify one request; throws VerifyError. */
+    async verify(input) {
+        const h = lower(input.headers);
+        const now = this.clock();
+        if (!h["signature-input"] || !h["signature"])
+            throw fail("missing_signature", "send Signature, Signature-Input and Signature-Agent (Web Bot Auth)");
+        let sp, sig;
+        try {
+            sp = wba.pickWebBotAuth(h["signature-input"]);
+            sig = wba.signatureBytes(h["signature"], sp.label);
+        }
+        catch (e) {
+            throw fail("bad_signature", e.message);
+        }
+        for (const c of ["@method", "@authority", "@path", "signature-agent"]) {
+            if (!sp.components.includes(c))
+                throw fail("bad_signature", `${c} must be covered`);
+        }
+        const u = new URL(input.url);
+        if (u.search && !sp.components.includes("@query"))
+            throw fail("bad_signature", "@query must be covered when the URL has a query");
+        if (!h["signature-agent"])
+            throw fail("bad_signature", "Signature-Agent header is missing");
+        let agentUrl;
+        try {
+            agentUrl = wba.parseAgent(h["signature-agent"], sp.label);
+        }
+        catch (e) {
+            throw fail("bad_signature", e.message);
+        }
+        if ((sp.params.alg ?? "ed25519") !== "ed25519")
+            throw fail("bad_signature", `alg ${sp.params.alg} is not supported`);
+        const body = typeof input.body === "string" ? Buffer.from(input.body) : (input.body ?? new Uint8Array());
+        if (sp.components.includes("content-digest")) {
+            if (h["content-digest"] !== wba.contentDigest(body))
+                throw fail("digest_mismatch", "the body doesn't match Content-Digest");
+        }
+        else if (body.length) {
+            throw fail("bad_signature", "a request body must be covered by content-digest");
+        }
+        const created = Number.parseInt(sp.params.created ?? "", 10);
+        if (!Number.isFinite(created))
+            throw fail("bad_signature", "created is required");
+        if (Math.abs(now - created) > this.maxSkew)
+            throw fail("clock_skew", `created is ${Math.round(now - created)}s from the server clock`);
+        if (sp.params.expires !== undefined) {
+            const expires = Number.parseInt(sp.params.expires, 10);
+            if (!Number.isFinite(expires) || now > expires || expires - created > wba.MAX_LIFETIME)
+                throw fail("clock_skew", "signature expired");
+        }
+        const nonce = sp.params.nonce;
+        if (!nonce)
+            throw fail("bad_signature", "nonce is required");
+        const identity = this.identityOf(agentUrl);
+        // Before any fetch: callers outside the trust list can't make this API fetch directories.
+        if (!this.trust.includes("*") && !this.trust.includes(identity))
+            throw fail("untrusted", `${identity} is not in this API's trust list`, 403);
+        const kid = sp.params.keyid ?? "";
+        const { key, pub } = await this.lookup(agentUrl, identity, kid);
+        const values = {
+            "@method": input.method.toUpperCase(),
+            "@authority": (h["host"] ?? u.host).toLowerCase(),
+            "@path": u.pathname || "/",
+            "@query": u.search || "?",
+        };
+        const comps = sp.components.map((c) => {
+            if (c in values)
+                return [c, values[c]];
+            if (c.startsWith("@"))
+                throw fail("bad_signature", `unsupported component ${c}`);
+            if (h[c] === undefined)
+                throw fail("bad_signature", `covered header ${c} is missing`);
+            return [c, h[c]];
+        });
+        const publicKey = createPublicKey({ key: Buffer.concat([SPKI_ED25519_PREFIX, pub]), format: "der", type: "spki" });
+        if (!edVerify(null, wba.base(comps, sp.raw), publicKey, sig))
+            throw fail("bad_signature", "the signature doesn't match the request");
+        if (!(await this.nonces.add(`${agentUrl} ${nonce}`, 2 * this.maxSkew)))
+            throw fail("nonce_replayed", "this signature was already accepted once");
+        return { identity, keyName: key.messh_name ?? "", keyId: kid, fingerprint: key.messh_fingerprint ?? "", agentUrl, created };
+    }
+    /** Verify a fetch Request (Workers, Hono, Next.js route handlers, Deno, Bun). */
+    async verifyRequest(request) {
+        const body = request.body ? await readLimited(request.clone(), this.maxBodyBytes) : undefined;
+        return this.verify({ method: request.method, url: request.url, headers: request.headers, body });
+    }
+    identityOf(agentUrl) {
+        let u;
+        try {
+            u = new URL(agentUrl);
+        }
+        catch {
+            throw fail("bad_signature", "Signature-Agent is not a URL");
+        }
+        if (!this.registries.has(u.origin))
+            throw fail("untrusted", `Signature-Agent ${agentUrl} is not a messh registry this API accepts`, 403);
+        const id = u.pathname.replace(/^\/+|\/+$/g, "");
+        if (!IDENTITY.test(id))
+            throw fail("unknown_key", "Signature-Agent must be <registry>/<user>");
+        return id;
+    }
+    /**
+     * The signer's key for kid. Directories are cached for cacheTtl; an unknown
+     * kid refetches at most every MIN_REFRESH s (so a key published a moment ago
+     * works), unknown identities are remembered the same way, one fetch per
+     * directory runs at a time, and while messh is unreachable cached keys keep
+     * working for staleIfError.
+     */
+    async lookup(agentUrl, identity, kid) {
+        const find = (dir) => {
+            for (const key of dir?.keys ?? []) {
+                if (key.kid !== kid)
+                    continue;
+                const pub = wba.jwkPublicKey(key);
+                if (pub)
+                    return { key, pub };
+            }
+            return undefined;
+        };
+        const found = (dir) => {
+            const hit = find(dir);
+            if (hit)
+                return hit;
+            throw dir === null
+                ? fail("unknown_key", `there's no messh identity at ${agentUrl}`)
+                : fail("unknown_key", `keyid ${kid} is not an active key of ${agentUrl}; publish it with messh publish`);
+        };
+        if (this.directory)
+            return found(typeof this.directory === "function" ? await this.directory(agentUrl, identity) : this.directory);
+        const now = this.clock();
+        let e = this.cache.get(agentUrl);
+        const age = e?.at === undefined ? Infinity : now - e.at;
+        if (age < this.cacheTtl) {
+            const hit = find(e.dir);
+            if (hit)
+                return hit;
+            if (age < MIN_REFRESH)
+                return found(e.dir);
+        }
+        if (e?.failedAt === undefined || now - e.failedAt >= RETRY_AFTER) {
+            const dir = await this.fetchOnce(agentUrl, identity);
+            if (dir !== undefined) {
+                this.store(agentUrl, { dir, at: now });
+                return found(dir);
+            }
+            e = { ...e, failedAt: now };
+            this.store(agentUrl, e);
+        }
+        // messh is unreachable: keep verifying with the cached directory for a while.
+        if (e?.dir !== undefined && now - e.at < this.staleIfError)
+            return found(e.dir);
+        throw fail("unknown_key", `key directory for ${agentUrl} is unavailable`);
+    }
+    /** Fetch a directory: the directory, null for no such identity, undefined if messh couldn't answer. One request per URL at a time. */
+    fetchOnce(agentUrl, identity) {
+        let p = this.inflight.get(agentUrl);
+        if (!p) {
+            const url = `${this.registries.get(new URL(agentUrl).origin)}/${identity}${wba.DIRECTORY_PATH}`;
+            p = (async () => {
+                try {
+                    const res = await fetch(url, {
+                        headers: { accept: "application/http-message-signatures-directory+json, application/json", "user-agent": `messh-js/${VERSION}` },
+                        signal: AbortSignal.timeout(this.timeoutMs),
+                    });
+                    if (res.status === 404)
+                        return null;
+                    const dir = res.ok ? (await res.json()) : undefined;
+                    return dir && Array.isArray(dir.keys) ? dir : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })().finally(() => this.inflight.delete(agentUrl));
+            this.inflight.set(agentUrl, p);
+        }
+        return p;
+    }
+    store(agentUrl, e) {
+        this.cache.delete(agentUrl); // re-insert: Map order is then least recently stored first
+        this.cache.set(agentUrl, e);
+        while (this.cache.size > MAX_ENTRIES)
+            this.cache.delete(this.cache.keys().next().value);
+    }
+}
+async function readLimited(request, max) {
+    const reader = request.body.getReader();
+    const parts = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.length;
+        if (size > max) {
+            // Not awaited: on a cloned request the cancel settles only once the original's branch is done too.
+            reader.cancel().catch(() => { });
+            throw fail("body_too_large", `the request body is over this API's limit of ${max} bytes`, 413);
+        }
+        parts.push(value);
+    }
+    return Buffer.concat(parts);
+}
+function lower(headers) {
+    const out = {};
+    const add = (k, v) => {
+        k = k.toLowerCase();
+        v = v.trim();
+        out[k] = k in out ? `${out[k]}, ${v}` : v;
+    };
+    if (typeof headers.forEach === "function" && typeof headers.get === "function") {
+        headers.forEach((v, k) => add(k, v));
+    }
+    else {
+        for (const [k, v] of Object.entries(headers)) {
+            if (Array.isArray(v))
+                v.forEach((x) => add(k, x));
+            else if (v !== undefined)
+                add(k, v);
+        }
+    }
+    return out;
+}
+/** Create a verifier (reuse it; it caches keys). */
+export function createVerifier(options) {
+    return new Verifier(options);
+}
+/**
+ * Express / Connect middleware. Mount it before express.json(): it reads
+ * the raw body, verifies, then sets req.rawBody, req.agent and (for JSON)
+ * req.body. Set `trustProxy` if TLS ends at a proxy (uses X-Forwarded-Proto).
+ */
+export function messhAuth(options) {
+    const v = options.verifier ?? new Verifier(options);
+    return (req, res, next) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size <= v.maxBodyBytes)
+                chunks.push(c);
+        });
+        req.on("error", next);
+        req.on("end", async () => {
+            if (size > v.maxBodyBytes) {
+                res.status(413).json(fail("body_too_large", `the request body is over this API's limit of ${v.maxBodyBytes} bytes`, 413).toJSON());
+                return;
+            }
+            const body = Buffer.concat(chunks);
+            const proto = (options.trustProxy && String(req.headers["x-forwarded-proto"] ?? "").split(",")[0]) || req.protocol || "http";
+            const url = `${proto}://${req.headers.host}${req.originalUrl ?? req.url}`;
+            try {
+                req.agent = await v.verify({ method: req.method, url, headers: req.headers, body });
+            }
+            catch (e) {
+                const err = e instanceof VerifyError ? e : fail("bad_signature", String(e));
+                if (err.status === 401)
+                    res.setHeader("Accept-Signature", ACCEPT_SIGNATURE);
+                res.status(err.status).json(err.toJSON());
+                return;
+            }
+            req.rawBody = body;
+            if (body.length && String(req.headers["content-type"] ?? "").includes("json")) {
+                try {
+                    req.body = JSON.parse(body.toString("utf8"));
+                }
+                catch { /* leave unparsed */ }
+            }
+            req._body = true; // body-parser: already read
+            next();
+        });
+    };
+}

package/dist/wba.d.ts

@@ -0,0 +1,34 @@
+export declare const TAG = "web-bot-auth";
+export declare const LABEL = "sig1";
+export declare const DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+export declare const MAX_LIFETIME = 300;
+export interface JWK {
+    kty: string;
+    crv: string;
+    x: string;
+    kid?: string;
+    messh_name?: string;
+    messh_fingerprint?: string;
+}
+export interface Directory {
+    keys: JWK[];
+}
+export declare function thumbprint(publicKey: Uint8Array): string;
+/** SSH wire-format string: uint32 length, then the bytes. */
+export declare function sshString(b: Uint8Array): Buffer;
+/** The key's SSH fingerprint, as ssh-keygen -l and messh print it: SHA256:… */
+export declare function fingerprint(publicKey: Uint8Array): string;
+export declare function contentDigest(body: Uint8Array): string;
+export declare const quote: (s: string) => string;
+export declare function params(names: string[], created: number, expires: number, keyid: string, nonce: string): string;
+export declare function base(components: [string, string][], sigParams: string): Uint8Array;
+export interface SigParams {
+    label: string;
+    components: string[];
+    params: Record<string, string>;
+    raw: string;
+}
+export declare function pickWebBotAuth(header: string): SigParams;
+export declare function signatureBytes(header: string, label: string): Uint8Array;
+export declare function parseAgent(header: string, label: string): string;
+export declare function jwkPublicKey(jwk: JWK): Uint8Array | null;