@melaya/runner 1.0.118 → 1.1.0

package/dist/browserGrantVerify.d.ts

@@ -0,0 +1,91 @@
+import { type KeyObject } from "node:crypto";
+export declare const BROWSER_EFFECT_CLASSES: readonly ["read", "navigate", "message", "publish", "consent", "upload", "download", "purchase", "account_change", "data_export", "destructive"];
+export type BrowserEffectClass = (typeof BROWSER_EFFECT_CLASSES)[number];
+export declare const BROWSER_EFFECT_RANK: Readonly<Record<BrowserEffectClass, number>>;
+export declare const BROWSER_GRANT_ISSUER = "melaya-control";
+export declare const BROWSER_GRANT_ALG: "EdDSA";
+/** The algorithm allowlist is exactly one entry by design. */
+export declare const ALLOWED_ALGS: readonly string[];
+export interface BrowserGrantClaims {
+    sub: string;
+    aud: string[];
+    tenant: string;
+    project: string;
+    run: string;
+    runnerDevice: string;
+    socketGeneration: number;
+    browserSession: string;
+    target: {
+        ref: string;
+    };
+    profile?: string;
+    space?: string;
+    originScopes: string[];
+    actionScopes: BrowserEffectClass[];
+    effectCeiling: BrowserEffectClass;
+}
+export interface BrowserGrant extends BrowserGrantClaims {
+    iss: typeof BROWSER_GRANT_ISSUER;
+    kid: string;
+    jti: string;
+    iat: number;
+    nbf: number;
+    exp: number;
+}
+export type BrowserGrantErrorCode = "malformed" | "alg_not_allowed" | "kid_unknown" | "bad_signature" | "iss_mismatch" | "aud_mismatch" | "expired" | "not_yet_valid" | "claims_invalid" | "revoked" | "replayed" | "replay_store_unavailable";
+export declare class BrowserGrantError extends Error {
+    readonly code: BrowserGrantErrorCode;
+    constructor(code: BrowserGrantErrorCode, message: string);
+}
+export interface ReplayStore {
+    /** Atomically register a jti. Returns true exactly once per jti
+     *  (first caller wins); false means the grant was already used.
+     *  Implementations MUST throw (not return true) when the store is
+     *  unreachable: the verifier maps that to replay_store_unavailable
+     *  and refuses the grant (fail closed). */
+    registerOnce(jti: string, ttlMs: number): Promise<boolean>;
+}
+/** In-process replay store for the single-runner case. The runner is
+ *  one OS process, and every grant is bound to THIS runner device via
+ *  `aud`, so process-local single-use is sufficient on this side; the
+ *  server keeps the authoritative Redis store for its own paths. */
+export declare function createInMemoryReplayStore(): ReplayStore;
+/** Accepts base64 of a 32-byte raw Ed25519 public key (the wire form
+ *  the server ships via getBrowserGrantPublicKeys) or of an SPKI DER
+ *  key, or an already-built KeyObject. Throws BrowserGrantError
+ *  ("kid_unknown") on anything that does not decode to Ed25519. */
+export declare function toPublicKeyObject(key: string | KeyObject, kid: string): KeyObject;
+/** Optional operator pinning: parse MEL_BROWSER_GRANT_PUBLIC_KEYS
+ *  ("<kid>=<base64>,..." in the same format the server env uses) into
+ *  a publicKeysByKid map. The normal delivery path is the server
+ *  pushing getBrowserGrantPublicKeys() output over the socket; this
+ *  env var lets a security-conscious operator pin keys locally so a
+ *  compromised socket cannot swap them. */
+export declare function loadPinnedPublicKeysFromEnv(): Record<string, string>;
+export declare const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+export interface VerifyBrowserGrantOptions {
+    /** This verifier's own identity (runner device id, or extension
+     *  instance id on the extension path). Must appear in `aud`. */
+    expectedAud: string;
+    /** kid -> public key (base64 raw 32-byte / base64 SPKI DER /
+     *  KeyObject). Delivered by the server or pinned via env. */
+    publicKeysByKid: Record<string, string | KeyObject>;
+    /** Single-use jti store. Use createInMemoryReplayStore() on the
+     *  runner. REQUIRED: single-use is part of the trust contract. */
+    replayStore: ReplayStore;
+    /** Optional revocation hook (server RPC or local cache). Returning
+     *  true, or throwing, rejects the grant. When omitted, revocation
+     *  is enforced only by expiry (acceptable for 120s grants when the
+     *  transport also delivers explicit stop signals). */
+    isRevoked?: (jti: string) => Promise<boolean>;
+    /** Clock tolerance in seconds for exp/nbf/iat. Default 30. */
+    clockToleranceSeconds?: number;
+    /** Test hook: current time in epoch ms. Default Date.now(). */
+    nowMs?: number;
+}
+/** Verify a browserGrant compact JWS. Resolves to the typed, verified
+ *  BrowserGrant on success; throws BrowserGrantError on EVERY reject
+ *  path (fail closed). The jti is consumed in the replay store as the
+ *  final step, so a grant that fails any earlier check is NOT burned
+ *  and a retried delivery of a valid token still works exactly once. */
+export declare function verifyBrowserGrant(token: string, opts: VerifyBrowserGrantOptions): Promise<BrowserGrant>;

package/dist/browserGrantVerify.js

@@ -0,0 +1,353 @@
+// packages/runner/src/browserGrantVerify.ts
+//
+// Melaya Browser, Phase 0 (plan Section 0.6): runner-side VERIFIER for
+// the signed `browserGrant` capability token minted by the server
+// (server/src/services/browser/browserGrant.ts).
+//
+// Verification order (all checks fail closed with typed errors):
+//   1. compact-JWS shape and JSON decoding        -> "malformed"
+//   2. alg allowlist (exactly ["EdDSA"])          -> "alg_not_allowed"
+//   3. kid -> public key lookup                   -> "kid_unknown"
+//   4. Ed25519 signature over header.payload      -> "bad_signature"
+//   5. iss === "melaya-control"                   -> "iss_mismatch"
+//   6. expectedAud member of aud[]                -> "aud_mismatch"
+//   7. exp / nbf / iat with small tolerance (30s) -> "expired" / "not_yet_valid"
+//   8. structural claim checks + scope <= ceiling -> "claims_invalid"
+//   9. revocation hook (if provided)              -> "revoked"
+//  10. single-use jti via the replay store        -> "replayed"
+//
+// Zero dependencies: node:crypto supports Ed25519 natively on every
+// Node version the runner supports (engines >= 18).
+//
+// -- Keep in sync -------------------------------------------------------
+// `BrowserGrantClaims`, `BrowserGrant`, and the effect-class vocabulary
+// are DUPLICATED from server/src/services/browser/browserGrant.ts
+// because this published package cannot import server sources. Any
+// change on either side MUST be mirrored on the other.
+import { createPublicKey, verify as cryptoVerify } from "node:crypto";
+// ---------------------------------------------------------------------
+// Effect-class vocabulary (KEEP IN SYNC with server browserGrant.ts)
+// ---------------------------------------------------------------------
+export const BROWSER_EFFECT_CLASSES = [
+    "read",
+    "navigate",
+    "message",
+    "publish",
+    "consent",
+    "upload",
+    "download",
+    "purchase",
+    "account_change",
+    "data_export",
+    "destructive",
+];
+export const BROWSER_EFFECT_RANK = Object.fromEntries(BROWSER_EFFECT_CLASSES.map((e, i) => [e, i]));
+// ---------------------------------------------------------------------
+// Types (KEEP IN SYNC with server browserGrant.ts)
+// ---------------------------------------------------------------------
+export const BROWSER_GRANT_ISSUER = "melaya-control";
+export const BROWSER_GRANT_ALG = "EdDSA";
+/** The algorithm allowlist is exactly one entry by design. */
+export const ALLOWED_ALGS = [BROWSER_GRANT_ALG];
+export class BrowserGrantError extends Error {
+    code;
+    constructor(code, message) {
+        super(`[browserGrant:${code}] ${message}`);
+        this.name = "BrowserGrantError";
+        this.code = code;
+    }
+}
+/** In-process replay store for the single-runner case. The runner is
+ *  one OS process, and every grant is bound to THIS runner device via
+ *  `aud`, so process-local single-use is sufficient on this side; the
+ *  server keeps the authoritative Redis store for its own paths. */
+export function createInMemoryReplayStore() {
+    const seen = new Map(); // jti -> expiry epoch ms
+    let lastSweep = 0;
+    function sweep(now) {
+        // Amortized cleanup: at most once per 30s.
+        if (now - lastSweep < 30_000)
+            return;
+        lastSweep = now;
+        for (const [jti, until] of seen) {
+            if (until <= now)
+                seen.delete(jti);
+        }
+    }
+    return {
+        async registerOnce(jti, ttlMs) {
+            const now = Date.now();
+            sweep(now);
+            const existing = seen.get(jti);
+            if (existing !== undefined && existing > now)
+                return false;
+            seen.set(jti, now + Math.max(1000, ttlMs));
+            return true;
+        },
+    };
+}
+// ---------------------------------------------------------------------
+// Public-key handling
+// ---------------------------------------------------------------------
+// RFC 8410 fixed DER prefix for an Ed25519 SPKI public key.
+const SPKI_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
+const RAW_PUB_LEN = 32;
+/** Accepts base64 of a 32-byte raw Ed25519 public key (the wire form
+ *  the server ships via getBrowserGrantPublicKeys) or of an SPKI DER
+ *  key, or an already-built KeyObject. Throws BrowserGrantError
+ *  ("kid_unknown") on anything that does not decode to Ed25519. */
+export function toPublicKeyObject(key, kid) {
+    if (typeof key !== "string") {
+        if (key.asymmetricKeyType !== "ed25519") {
+            throw new BrowserGrantError("kid_unknown", `public key for kid '${kid}' is not ed25519`);
+        }
+        return key;
+    }
+    let raw;
+    try {
+        raw = Buffer.from(key, "base64");
+    }
+    catch {
+        throw new BrowserGrantError("kid_unknown", `public key for kid '${kid}' is not valid base64`);
+    }
+    try {
+        const der = raw.length === RAW_PUB_LEN ? Buffer.concat([SPKI_PREFIX, raw]) : raw;
+        const obj = createPublicKey({ key: der, format: "der", type: "spki" });
+        if (obj.asymmetricKeyType !== "ed25519") {
+            throw new Error("not ed25519");
+        }
+        return obj;
+    }
+    catch {
+        throw new BrowserGrantError("kid_unknown", `public key for kid '${kid}' must be base64 of a 32-byte raw or SPKI DER Ed25519 key`);
+    }
+}
+/** Optional operator pinning: parse MEL_BROWSER_GRANT_PUBLIC_KEYS
+ *  ("<kid>=<base64>,..." in the same format the server env uses) into
+ *  a publicKeysByKid map. The normal delivery path is the server
+ *  pushing getBrowserGrantPublicKeys() output over the socket; this
+ *  env var lets a security-conscious operator pin keys locally so a
+ *  compromised socket cannot swap them. */
+export function loadPinnedPublicKeysFromEnv() {
+    const out = {};
+    const raw = process.env.MEL_BROWSER_GRANT_PUBLIC_KEYS || "";
+    for (const entry of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
+        const eq = entry.indexOf("=");
+        if (eq <= 0)
+            continue;
+        out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------
+// Verifier
+// ---------------------------------------------------------------------
+export const DEFAULT_CLOCK_TOLERANCE_SECONDS = 30;
+/** Sanity ceiling: matches the server's MAX_TTL_SECONDS. A "valid"
+ *  token claiming a longer life than the issuer can mint is forged or
+ *  corrupt, so it is rejected regardless of signature. */
+const MAX_LIFETIME_SECONDS = 900;
+function b64urlJson(part, what) {
+    let buf;
+    try {
+        buf = Buffer.from(part, "base64url");
+    }
+    catch {
+        throw new BrowserGrantError("malformed", `${what} is not valid base64url`);
+    }
+    try {
+        return JSON.parse(buf.toString("utf8"));
+    }
+    catch {
+        throw new BrowserGrantError("malformed", `${what} is not valid JSON`);
+    }
+}
+function isNonEmptyString(v) {
+    return typeof v === "string" && v.length > 0;
+}
+function validateClaimStructure(p) {
+    const bad = (name) => {
+        throw new BrowserGrantError("claims_invalid", `claim '${name}' is missing or malformed`);
+    };
+    if (!isNonEmptyString(p.sub))
+        bad("sub");
+    if (!isNonEmptyString(p.jti))
+        bad("jti");
+    if (!isNonEmptyString(p.tenant))
+        bad("tenant");
+    if (!isNonEmptyString(p.project))
+        bad("project");
+    if (!isNonEmptyString(p.run))
+        bad("run");
+    if (!isNonEmptyString(p.runnerDevice))
+        bad("runnerDevice");
+    if (!isNonEmptyString(p.browserSession))
+        bad("browserSession");
+    if (!Number.isInteger(p.socketGeneration) || p.socketGeneration < 0)
+        bad("socketGeneration");
+    const target = p.target;
+    if (!target || typeof target !== "object" || !isNonEmptyString(target.ref))
+        bad("target.ref");
+    if (p.profile !== undefined && !isNonEmptyString(p.profile))
+        bad("profile");
+    if (p.space !== undefined && !isNonEmptyString(p.space))
+        bad("space");
+    if (!Array.isArray(p.originScopes) || p.originScopes.some((o) => !isNonEmptyString(o))) {
+        bad("originScopes");
+    }
+    if (!isNonEmptyString(p.effectCeiling) || !(p.effectCeiling in BROWSER_EFFECT_RANK))
+        bad("effectCeiling");
+    const ceiling = BROWSER_EFFECT_RANK[p.effectCeiling];
+    if (!Array.isArray(p.actionScopes) || p.actionScopes.length === 0)
+        bad("actionScopes");
+    for (const scope of p.actionScopes) {
+        if (!isNonEmptyString(scope) || !(scope in BROWSER_EFFECT_RANK))
+            bad("actionScopes");
+        if (BROWSER_EFFECT_RANK[scope] > ceiling) {
+            throw new BrowserGrantError("claims_invalid", `actionScope '${scope}' exceeds effectCeiling '${String(p.effectCeiling)}'`);
+        }
+    }
+}
+/** Verify a browserGrant compact JWS. Resolves to the typed, verified
+ *  BrowserGrant on success; throws BrowserGrantError on EVERY reject
+ *  path (fail closed). The jti is consumed in the replay store as the
+ *  final step, so a grant that fails any earlier check is NOT burned
+ *  and a retried delivery of a valid token still works exactly once. */
+export async function verifyBrowserGrant(token, opts) {
+    if (!opts || !isNonEmptyString(opts.expectedAud)) {
+        throw new BrowserGrantError("aud_mismatch", "verifier misconfigured: expectedAud is required");
+    }
+    if (!opts.replayStore) {
+        throw new BrowserGrantError("replay_store_unavailable", "verifier misconfigured: replayStore is required");
+    }
+    // 1. Shape
+    if (typeof token !== "string" || token.length === 0 || token.length > 16_384) {
+        throw new BrowserGrantError("malformed", "token is empty, not a string, or oversized");
+    }
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        throw new BrowserGrantError("malformed", "token is not a three-part compact JWS");
+    }
+    const header = b64urlJson(parts[0], "header");
+    // 2. Algorithm allowlist (never trust the header beyond routing)
+    if (!ALLOWED_ALGS.includes(header.alg)) {
+        throw new BrowserGrantError("alg_not_allowed", `alg '${String(header.alg)}' is not in [${ALLOWED_ALGS.join(", ")}]`);
+    }
+    // 3. kid -> public key
+    if (!isNonEmptyString(header.kid)) {
+        throw new BrowserGrantError("kid_unknown", "header has no kid");
+    }
+    const kid = header.kid;
+    const keyMaterial = opts.publicKeysByKid[kid];
+    if (keyMaterial === undefined) {
+        throw new BrowserGrantError("kid_unknown", `no public key for kid '${kid}'`);
+    }
+    const publicKey = toPublicKeyObject(keyMaterial, kid);
+    // 4. Signature over the exact signing input
+    let sig;
+    try {
+        sig = Buffer.from(parts[2], "base64url");
+    }
+    catch {
+        throw new BrowserGrantError("malformed", "signature is not valid base64url");
+    }
+    const signingInput = Buffer.from(parts[0] + "." + parts[1], "utf8");
+    let ok = false;
+    try {
+        ok = cryptoVerify(null, signingInput, publicKey, sig);
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok) {
+        throw new BrowserGrantError("bad_signature", `signature verification failed under kid '${kid}'`);
+    }
+    // Only now is the payload trustworthy enough to inspect.
+    const p = b64urlJson(parts[1], "payload");
+    // 5. Issuer
+    if (p.iss !== BROWSER_GRANT_ISSUER) {
+        throw new BrowserGrantError("iss_mismatch", `iss '${String(p.iss)}' is not '${BROWSER_GRANT_ISSUER}'`);
+    }
+    // 6. Audience: our own id must be in the list
+    if (!Array.isArray(p.aud) || p.aud.some((a) => !isNonEmptyString(a))) {
+        throw new BrowserGrantError("aud_mismatch", "aud is not a string array");
+    }
+    if (!p.aud.includes(opts.expectedAud)) {
+        throw new BrowserGrantError("aud_mismatch", `aud does not include '${opts.expectedAud}'`);
+    }
+    // 7. Time window with tolerance
+    const tol = Math.max(0, opts.clockToleranceSeconds ?? DEFAULT_CLOCK_TOLERANCE_SECONDS);
+    const now = Math.floor((opts.nowMs ?? Date.now()) / 1000);
+    const { iat, nbf, exp } = p;
+    if (!Number.isFinite(iat) || !Number.isFinite(nbf) || !Number.isFinite(exp)) {
+        throw new BrowserGrantError("claims_invalid", "iat/nbf/exp must be numeric");
+    }
+    if (exp <= now - tol) {
+        throw new BrowserGrantError("expired", `exp ${exp} is in the past (now ${now}, tolerance ${tol}s)`);
+    }
+    if (nbf > now + tol) {
+        throw new BrowserGrantError("not_yet_valid", `nbf ${nbf} is in the future (now ${now}, tolerance ${tol}s)`);
+    }
+    if (iat > now + tol) {
+        throw new BrowserGrantError("not_yet_valid", `iat ${iat} is in the future (now ${now}, tolerance ${tol}s)`);
+    }
+    if (exp - iat > MAX_LIFETIME_SECONDS + tol) {
+        throw new BrowserGrantError("claims_invalid", `lifetime exceeds ${MAX_LIFETIME_SECONDS}s issuer maximum`);
+    }
+    if (p.kid !== undefined && p.kid !== kid) {
+        throw new BrowserGrantError("claims_invalid", "payload kid disagrees with header kid");
+    }
+    // 8. Structural claims + scope/ceiling relation
+    validateClaimStructure(p);
+    const jti = p.jti;
+    // 9. Revocation hook (before burning the jti). A throwing hook
+    //    rejects: unreachable revocation infrastructure means we cannot
+    //    prove the grant is still live.
+    if (opts.isRevoked) {
+        let revoked;
+        try {
+            revoked = await opts.isRevoked(jti);
+        }
+        catch (e) {
+            throw new BrowserGrantError("revoked", `revocation check failed, refusing grant: ${e?.message || e}`);
+        }
+        if (revoked) {
+            throw new BrowserGrantError("revoked", `jti '${jti}' is revoked`);
+        }
+    }
+    // 10. Single-use consumption, last so failed earlier checks never
+    //     burn a valid token. TTL covers remaining life + tolerance.
+    const replayTtlMs = Math.max(1000, (exp - now + tol) * 1000);
+    let first;
+    try {
+        first = await opts.replayStore.registerOnce(jti, replayTtlMs);
+    }
+    catch (e) {
+        throw new BrowserGrantError("replay_store_unavailable", `replay store unreachable, refusing grant: ${e?.message || e}`);
+    }
+    if (!first) {
+        throw new BrowserGrantError("replayed", `jti '${jti}' was already used`);
+    }
+    return {
+        iss: BROWSER_GRANT_ISSUER,
+        kid,
+        jti,
+        iat: iat,
+        nbf: nbf,
+        exp: exp,
+        sub: p.sub,
+        aud: p.aud,
+        tenant: p.tenant,
+        project: p.project,
+        run: p.run,
+        runnerDevice: p.runnerDevice,
+        socketGeneration: p.socketGeneration,
+        browserSession: p.browserSession,
+        target: { ref: p.target.ref },
+        profile: p.profile,
+        space: p.space,
+        originScopes: p.originScopes,
+        actionScopes: p.actionScopes,
+        effectCeiling: p.effectCeiling,
+    };
+}

package/dist/browserProvisioner.d.ts

@@ -0,0 +1,33 @@
+export type BrowserEngineId = "chrome" | "edge" | "brave" | "chromium";
+export interface InstalledEngine {
+    engine: BrowserEngineId;
+    executablePath: string;
+    /** Best-effort version ("139.0.7258.67" style); "" when undetectable. */
+    version: string;
+    /** Playwright channel name when launchable via channel, else null
+     *  (brave has no Playwright channel: launched via executablePath). */
+    channel: "chrome" | "msedge" | null;
+    /** Engine-specific caveats the caller should surface to the user. */
+    quirks: string[];
+}
+export interface BrowserCapabilityReport {
+    engines: InstalledEngine[];
+    cdp: boolean;
+    provisioner: "v1";
+    platform: NodeJS.Platform;
+}
+export declare function discoverEngines(forceRefresh?: boolean): Promise<InstalledEngine[]>;
+export declare function capabilityReport(): Promise<BrowserCapabilityReport>;
+export declare class ProvisionError extends Error {
+    readonly code: "engine_not_installed" | "download_not_authorized" | "download_failed" | "engine_unsupported";
+    readonly instructions?: string;
+    constructor(code: ProvisionError["code"], message: string, instructions?: string);
+}
+/** Resolve an engine to a launchable executable. NEVER downloads unless
+ *  allowDownload is explicitly true, and even then only the
+ *  Playwright-bundled Chromium is downloadable (Chrome/Edge/Brave are
+ *  user-installed products we will not fetch on the user's behalf). */
+export declare function ensureEngine(engine: BrowserEngineId, opts?: {
+    allowDownload?: boolean;
+    log?: (m: string) => void;
+}): Promise<InstalledEngine>;