mrplex 0.0.1

package/dist/shell/oidc.d.ts

@@ -0,0 +1,62 @@
+/**
+ * OIDC verification — auth-shell plan §1 (authn front 2), WS5.
+ *
+ * Verify a caller's JWT against the IdP's JWKS (issuer + audience pinned in
+ * shell config), then match the verified claims to a policy principal by its
+ * `oidc.sub` / `oidc.email` binding. Where the matched principal has no static
+ * `author`, derive one from the token as `name <email>` — the convention and
+ * the credential line up by construction (plan §3).
+ *
+ * Shared by the HTTP front and `mcp-stdio`'s `MRPLEX_SHELL_TOKEN` front: both
+ * hand a bearer JWT here and get back a principal id + author. The shell is the
+ * OAuth *resource server*; the authorization-server role belongs entirely to
+ * the IdP (this is also the on-ramp to MCP's OAuth 2.1 story).
+ */
+import type { Policy } from "./policy.js";
+export type OidcConfig = {
+    /** Pinned issuer (`iss` claim must match). */
+    issuer: string;
+    /** Pinned audience (`aud` claim must include this). */
+    audience: string;
+    /** JWKS endpoint URL. Defaults to `${issuer}/.well-known/jwks.json` if absent. */
+    jwksUri?: string;
+};
+/** The subset of verified claims the shell binds/derives identity from. */
+export type VerifiedClaims = {
+    sub: string;
+    email?: string;
+    /** OIDC `email_verified` — whether the IdP has verified ownership of `email`. */
+    email_verified?: boolean;
+    name?: string;
+};
+/** Resolution of a verified token: which principal, and the author to stamp. */
+export type OidcResolution = {
+    principalId: string;
+    author: string;
+};
+export declare class OidcError extends Error {
+    constructor(message: string);
+}
+/**
+ * A verifier bound to one IdP. Construction sets up the (cached, auto-rotating)
+ * remote JWKS; `verify()` checks a token and returns its claims. Kept as a
+ * factory so the JWKS fetcher is created once and reused across requests.
+ */
+export type OidcVerifier = {
+    verify: (jwt: string) => Promise<VerifiedClaims>;
+};
+export declare function createOidcVerifier(config: OidcConfig): OidcVerifier;
+/**
+ * Match verified claims to a policy principal and resolve the author. A
+ * principal binds via `oidc.sub` (exact) or `oidc.email` (exact); `sub` wins
+ * when both could match. The author is the principal's static `author` if set,
+ * else derived as `${name} <${email}>` (or just `<email>` when the token
+ * carries no display name). Throws `OidcError` when no principal binds or no
+ * author can be formed.
+ *
+ * Email binding requires `email_verified === true`: an IdP that lets a user set
+ * an arbitrary unverified `email` (or exposes federated emails without
+ * re-verification) would otherwise let a hostile user claim another principal's
+ * grants. `sub` binding is unaffected — it's issuer-namespaced and IdP-controlled.
+ */
+export declare function resolvePrincipalFromClaims(policy: Policy, claims: VerifiedClaims): OidcResolution;

package/dist/shell/oidc.js

@@ -0,0 +1,102 @@
+/**
+ * OIDC verification — auth-shell plan §1 (authn front 2), WS5.
+ *
+ * Verify a caller's JWT against the IdP's JWKS (issuer + audience pinned in
+ * shell config), then match the verified claims to a policy principal by its
+ * `oidc.sub` / `oidc.email` binding. Where the matched principal has no static
+ * `author`, derive one from the token as `name <email>` — the convention and
+ * the credential line up by construction (plan §3).
+ *
+ * Shared by the HTTP front and `mcp-stdio`'s `MRPLEX_SHELL_TOKEN` front: both
+ * hand a bearer JWT here and get back a principal id + author. The shell is the
+ * OAuth *resource server*; the authorization-server role belongs entirely to
+ * the IdP (this is also the on-ramp to MCP's OAuth 2.1 story).
+ */
+import { createRemoteJWKSet, jwtVerify } from "jose";
+export class OidcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "OidcError";
+    }
+}
+export function createOidcVerifier(config) {
+    const jwksUri = config.jwksUri ?? `${config.issuer.replace(/\/$/, "")}/.well-known/jwks.json`;
+    const jwks = createRemoteJWKSet(new URL(jwksUri));
+    return {
+        verify: async (jwt) => {
+            let payload;
+            try {
+                const result = await jwtVerify(jwt, jwks, {
+                    issuer: config.issuer,
+                    audience: config.audience,
+                });
+                payload = result.payload;
+            }
+            catch (err) {
+                throw new OidcError(`token verification failed: ${err.message}`);
+            }
+            const sub = payload.sub;
+            if (typeof sub !== "string" || sub.length === 0) {
+                throw new OidcError("token has no `sub` claim");
+            }
+            const claims = { sub };
+            if (typeof payload.email === "string")
+                claims.email = payload.email;
+            // Some IdPs emit email_verified as the string "true"/"false"; accept both.
+            if (typeof payload.email_verified === "boolean") {
+                claims.email_verified = payload.email_verified;
+            }
+            else if (payload.email_verified === "true" || payload.email_verified === "false") {
+                claims.email_verified = payload.email_verified === "true";
+            }
+            if (typeof payload.name === "string")
+                claims.name = payload.name;
+            return claims;
+        },
+    };
+}
+/**
+ * Match verified claims to a policy principal and resolve the author. A
+ * principal binds via `oidc.sub` (exact) or `oidc.email` (exact); `sub` wins
+ * when both could match. The author is the principal's static `author` if set,
+ * else derived as `${name} <${email}>` (or just `<email>` when the token
+ * carries no display name). Throws `OidcError` when no principal binds or no
+ * author can be formed.
+ *
+ * Email binding requires `email_verified === true`: an IdP that lets a user set
+ * an arbitrary unverified `email` (or exposes federated emails without
+ * re-verification) would otherwise let a hostile user claim another principal's
+ * grants. `sub` binding is unaffected — it's issuer-namespaced and IdP-controlled.
+ */
+export function resolvePrincipalFromClaims(policy, claims) {
+    let matchBySub;
+    let matchByEmail;
+    const emailUsable = claims.email !== undefined && claims.email_verified === true;
+    for (const [id, principal] of Object.entries(policy.principals)) {
+        const binding = principal.oidc;
+        if (!binding)
+            continue;
+        if (binding.sub !== undefined && binding.sub === claims.sub)
+            matchBySub = id;
+        if (emailUsable && binding.email !== undefined && binding.email === claims.email) {
+            matchByEmail = id;
+        }
+    }
+    const principalId = matchBySub ?? matchByEmail;
+    if (principalId === undefined) {
+        throw new OidcError("no policy principal binds this token's sub/email");
+    }
+    const principal = policy.principals[principalId];
+    const author = principal?.author ?? deriveAuthor(claims);
+    if (author === undefined) {
+        throw new OidcError(`principal "${principalId}" has no static author and the token carries no email to derive one`);
+    }
+    return { principalId, author };
+}
+/** `name <email>` / `<email>` from claims, or undefined when there's no email. */
+function deriveAuthor(claims) {
+    if (claims.email === undefined)
+        return undefined;
+    return claims.name !== undefined ? `${claims.name} <${claims.email}>` : `<${claims.email}>`;
+}
+//# sourceMappingURL=oidc.js.map

package/dist/shell/oidc.js.map

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

package/dist/shell/policy.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Policy + entitlement — auth-shell plan §1, §3, WS1.
+ *
+ * The shell's one stable internal seam is the compiled `Entitlement`: every
+ * authn front, whatever its mechanism (API key today, OIDC tomorrow, capability
+ * token someday), resolves a credential to a principal id and then to this
+ * tuple, and the guard consumes *only* this tuple. Neither side knows the other
+ * exists.
+ *
+ * A declarative YAML policy file names principals, roles, and grants. A
+ * **grant** — `{ repo, read?, write? }` — is the human-facing vocabulary: it
+ * pairs a repo pattern with path globs per direction. `compile()` splits each
+ * grant into the entitlement's two `ScopeClaim` lists — read globs feed
+ * `Entitlement.read` (forwarded to the engine as `ctx.scope`), write globs feed
+ * `Entitlement.write` (enforced BY THE SHELL against write-op paths). One glob
+ * dialect throughout (the engine's `kernel/auth/glob.ts`), no deny rules beyond
+ * `!` negation inside a list.
+ *
+ * `compile(policy, principalId)` is a pure function — no I/O — so it is trivially
+ * unit-testable and so a future policy store (SQLite, an IdP's groups, capability
+ * tokens) can replace the loader behind it without the guard or the fronts
+ * noticing (plan decision 3).
+ */
+import type { ScopeClaim } from "../kernel/context.js";
+/**
+ * The compiled contract the guard consumes. Fronts compile *to* it; the guard
+ * reads *only* it. Stable across authn mechanisms (plan decision 2).
+ */
+export type Entitlement = {
+    /** Identity the shell stamps on writes (`ctx.author`), derived from the credential. */
+    author: string;
+    /** Read visibility — forwarded verbatim as `ctx.scope`. */
+    read: ScopeClaim[];
+    /** Enforced BY THE SHELL against write-op target paths. */
+    write: ScopeClaim[];
+    /** May run repos.create/rename/delete/set_path_config/set_link_config + link mutations. */
+    destructive: boolean;
+    /** May supply a caller-chosen author instead of the derived one. */
+    impersonate: boolean;
+};
+/**
+ * A grant names both directions together: a repo pattern plus optional read
+ * and write path globs. Omitting a direction grants nothing in it.
+ */
+export type Grant = {
+    repo: string | string[];
+    read?: string | string[];
+    write?: string | string[];
+};
+/** A role is a grant bundle plus the two op-level booleans. */
+export type Role = {
+    grants: Grant[];
+    destructive?: boolean;
+    impersonate?: boolean;
+};
+/** OIDC binding — how a verified token's claims match this principal. */
+export type OidcBinding = {
+    email?: string;
+    sub?: string;
+};
+export type Principal = {
+    /** Static author. Required unless `oidc` is present (then derived at login). */
+    author?: string;
+    roles: string[];
+    /** `sha256:<hex>` API-key hashes. Issuance/revocation is a diff to this file. */
+    keys?: string[];
+    oidc?: OidcBinding;
+};
+export type Policy = {
+    roles: Record<string, Role>;
+    principals: Record<string, Principal>;
+};
+/**
+ * A policy-file or compile error. Distinct from `KernelError` — this is a
+ * startup/config fault (or an operator's `policy check`), not a per-call
+ * outcome handed back to an untrusted client.
+ */
+export declare class PolicyError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse YAML policy text into a validated `Policy`. Uses the `yaml` package's
+ * default core-schema parse (YAML 1.2 — no 1.1 implicit-typing footguns), then
+ * checks structure with precise, path-prefixed errors. Throws `PolicyError`.
+ */
+export declare function parsePolicy(text: string): Policy;
+/** Read + parse + validate a policy file. Throws `PolicyError` on any fault. */
+export declare function loadPolicyFile(path: string): Policy;
+/**
+ * Resolve a principal to its `Entitlement` — the union of its roles' grants and
+ * op booleans. Pure: no I/O, no clock, no globals. A principal's read/write
+ * claim lists are the concatenation of every role's grants (union semantics,
+ * §8.2); `destructive`/`impersonate` are OR'd across roles.
+ *
+ * `author` is `principal.author` when set. For an OIDC principal with no static
+ * author, the front derives `name <email>` from claims and passes it as
+ * `derivedAuthor`. If neither is available, this throws — a write with no
+ * attributable author is never stamped with the engine default here.
+ */
+export declare function compile(policy: Policy, principalId: string, derivedAuthor?: string): Entitlement;

package/dist/shell/policy.js

@@ -0,0 +1,232 @@
+/**
+ * Policy + entitlement — auth-shell plan §1, §3, WS1.
+ *
+ * The shell's one stable internal seam is the compiled `Entitlement`: every
+ * authn front, whatever its mechanism (API key today, OIDC tomorrow, capability
+ * token someday), resolves a credential to a principal id and then to this
+ * tuple, and the guard consumes *only* this tuple. Neither side knows the other
+ * exists.
+ *
+ * A declarative YAML policy file names principals, roles, and grants. A
+ * **grant** — `{ repo, read?, write? }` — is the human-facing vocabulary: it
+ * pairs a repo pattern with path globs per direction. `compile()` splits each
+ * grant into the entitlement's two `ScopeClaim` lists — read globs feed
+ * `Entitlement.read` (forwarded to the engine as `ctx.scope`), write globs feed
+ * `Entitlement.write` (enforced BY THE SHELL against write-op paths). One glob
+ * dialect throughout (the engine's `kernel/auth/glob.ts`), no deny rules beyond
+ * `!` negation inside a list.
+ *
+ * `compile(policy, principalId)` is a pure function — no I/O — so it is trivially
+ * unit-testable and so a future policy store (SQLite, an IdP's groups, capability
+ * tokens) can replace the loader behind it without the guard or the fronts
+ * noticing (plan decision 3).
+ */
+import { readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+/**
+ * A policy-file or compile error. Distinct from `KernelError` — this is a
+ * startup/config fault (or an operator's `policy check`), not a per-call
+ * outcome handed back to an untrusted client.
+ */
+export class PolicyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PolicyError";
+    }
+}
+// -----------------------------------------------------------------------------
+// Parse + validate.
+// -----------------------------------------------------------------------------
+const isString = (v) => typeof v === "string";
+const isStringList = (v) => Array.isArray(v) && v.every(isString);
+const isStrOrStrList = (v) => isString(v) || isStringList(v);
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * Parse YAML policy text into a validated `Policy`. Uses the `yaml` package's
+ * default core-schema parse (YAML 1.2 — no 1.1 implicit-typing footguns), then
+ * checks structure with precise, path-prefixed errors. Throws `PolicyError`.
+ */
+export function parsePolicy(text) {
+    let raw;
+    try {
+        raw = parseYaml(text);
+    }
+    catch (err) {
+        throw new PolicyError(`policy is not valid YAML: ${err.message}`);
+    }
+    if (!isObject(raw)) {
+        throw new PolicyError("policy must be a mapping with `roles` and `principals`");
+    }
+    const roles = validateRoles(raw.roles);
+    const principals = validatePrincipals(raw.principals, roles);
+    return { roles, principals };
+}
+/** Read + parse + validate a policy file. Throws `PolicyError` on any fault. */
+export function loadPolicyFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new PolicyError(`cannot read policy file ${path}: ${err.message}`);
+    }
+    return parsePolicy(text);
+}
+function validateGrant(g, where) {
+    if (!isObject(g))
+        throw new PolicyError(`${where} must be a mapping`);
+    if (!isStrOrStrList(g.repo)) {
+        throw new PolicyError(`${where}.repo must be a string or string[]`);
+    }
+    if (g.read !== undefined && !isStrOrStrList(g.read)) {
+        throw new PolicyError(`${where}.read must be a string or string[]`);
+    }
+    if (g.write !== undefined && !isStrOrStrList(g.write)) {
+        throw new PolicyError(`${where}.write must be a string or string[]`);
+    }
+    const grant = { repo: g.repo };
+    if (g.read !== undefined)
+        grant.read = g.read;
+    if (g.write !== undefined)
+        grant.write = g.write;
+    return grant;
+}
+function validateRoles(raw) {
+    if (raw === undefined)
+        return {};
+    if (!isObject(raw))
+        throw new PolicyError("`roles` must be a mapping of role name → role");
+    const roles = {};
+    for (const [name, value] of Object.entries(raw)) {
+        const where = `roles.${name}`;
+        if (!isObject(value))
+            throw new PolicyError(`${where} must be a mapping`);
+        if (value.grants !== undefined && !Array.isArray(value.grants)) {
+            throw new PolicyError(`${where}.grants must be a list`);
+        }
+        const grantsRaw = (value.grants ?? []);
+        const grants = grantsRaw.map((g, i) => validateGrant(g, `${where}.grants[${i}]`));
+        if (value.destructive !== undefined && typeof value.destructive !== "boolean") {
+            throw new PolicyError(`${where}.destructive must be a boolean`);
+        }
+        if (value.impersonate !== undefined && typeof value.impersonate !== "boolean") {
+            throw new PolicyError(`${where}.impersonate must be a boolean`);
+        }
+        const role = { grants };
+        if (value.destructive !== undefined)
+            role.destructive = value.destructive;
+        if (value.impersonate !== undefined)
+            role.impersonate = value.impersonate;
+        roles[name] = role;
+    }
+    return roles;
+}
+function validatePrincipals(raw, roles) {
+    if (!isObject(raw)) {
+        throw new PolicyError("`principals` must be a mapping of principal id → principal");
+    }
+    const principals = {};
+    for (const [id, value] of Object.entries(raw)) {
+        const where = `principals.${id}`;
+        if (!isObject(value))
+            throw new PolicyError(`${where} must be a mapping`);
+        if (value.author !== undefined && !isString(value.author)) {
+            throw new PolicyError(`${where}.author must be a string`);
+        }
+        if (!isStringList(value.roles)) {
+            throw new PolicyError(`${where}.roles must be a list of role names`);
+        }
+        for (const r of value.roles) {
+            if (!(r in roles)) {
+                throw new PolicyError(`${where}.roles references unknown role "${r}"`);
+            }
+        }
+        if (value.keys !== undefined && !isStringList(value.keys)) {
+            throw new PolicyError(`${where}.keys must be a list of "sha256:<hex>" strings`);
+        }
+        for (const k of value.keys ?? []) {
+            if (!/^sha256:[0-9a-f]{64}$/.test(k)) {
+                throw new PolicyError(`${where}.keys entry "${k}" must be "sha256:<64 hex chars>"`);
+            }
+        }
+        let oidc;
+        if (value.oidc !== undefined) {
+            if (!isObject(value.oidc))
+                throw new PolicyError(`${where}.oidc must be a mapping`);
+            if (value.oidc.email !== undefined && !isString(value.oidc.email)) {
+                throw new PolicyError(`${where}.oidc.email must be a string`);
+            }
+            if (value.oidc.sub !== undefined && !isString(value.oidc.sub)) {
+                throw new PolicyError(`${where}.oidc.sub must be a string`);
+            }
+            oidc = {};
+            if (value.oidc.email !== undefined)
+                oidc.email = value.oidc.email;
+            if (value.oidc.sub !== undefined)
+                oidc.sub = value.oidc.sub;
+        }
+        // A principal must have an author to stamp writes with, OR an OIDC binding
+        // that lets one be derived from claims at login (plan §3). A key-only
+        // principal with no author has no identity to attribute — reject it here,
+        // where the operator can see it, rather than stamping the engine default.
+        if (value.author === undefined && oidc === undefined) {
+            throw new PolicyError(`${where} needs an \`author\` or an \`oidc\` binding to derive one`);
+        }
+        const principal = { roles: value.roles };
+        if (value.author !== undefined)
+            principal.author = value.author;
+        if (value.keys !== undefined)
+            principal.keys = value.keys;
+        if (oidc !== undefined)
+            principal.oidc = oidc;
+        principals[id] = principal;
+    }
+    return principals;
+}
+// -----------------------------------------------------------------------------
+// Compile — the pure policy-evaluation function.
+// -----------------------------------------------------------------------------
+/**
+ * Resolve a principal to its `Entitlement` — the union of its roles' grants and
+ * op booleans. Pure: no I/O, no clock, no globals. A principal's read/write
+ * claim lists are the concatenation of every role's grants (union semantics,
+ * §8.2); `destructive`/`impersonate` are OR'd across roles.
+ *
+ * `author` is `principal.author` when set. For an OIDC principal with no static
+ * author, the front derives `name <email>` from claims and passes it as
+ * `derivedAuthor`. If neither is available, this throws — a write with no
+ * attributable author is never stamped with the engine default here.
+ */
+export function compile(policy, principalId, derivedAuthor) {
+    const principal = policy.principals[principalId];
+    if (!principal) {
+        throw new PolicyError(`unknown principal "${principalId}"`);
+    }
+    const read = [];
+    const write = [];
+    let destructive = false;
+    let impersonate = false;
+    for (const roleName of principal.roles) {
+        const role = policy.roles[roleName];
+        // validatePrincipals already checked role existence; guard anyway so a
+        // hand-built Policy object can't slip an unknown role past compile.
+        if (!role)
+            throw new PolicyError(`principal "${principalId}" references unknown role "${roleName}"`);
+        if (role.destructive)
+            destructive = true;
+        if (role.impersonate)
+            impersonate = true;
+        for (const grant of role.grants) {
+            if (grant.read !== undefined)
+                read.push({ repo: grant.repo, paths: grant.read });
+            if (grant.write !== undefined)
+                write.push({ repo: grant.repo, paths: grant.write });
+        }
+    }
+    const author = principal.author ?? derivedAuthor;
+    if (author === undefined) {
+        throw new PolicyError(`principal "${principalId}" has no static author and none was derived (OIDC login supplies it)`);
+    }
+    return { author, read, write, destructive, impersonate };
+}
+//# sourceMappingURL=policy.js.map

package/dist/shell/policy.js.map

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

package/dist/shell/proxy-policy.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Route-aware REST policy classification for proxy mode — auth-shell plan §1
+ * "Serve mode: fronting proxy", WS4.
+ *
+ * The fronting proxy is mrplex-aware (not a generic reverse proxy): it parses
+ * the known REST routes to decide what an entitlement must permit. Crucially,
+ * on the REST surface the URL path is *authoritative* for writes — a
+ * `PUT /repos/notes/docs/drafts/x.md` names its target path directly, and a
+ * MOVE carries source (URL) + destination (`Destination` header). So the proxy
+ * can replay the guard's §8.2 rules (both-endpoints on move, sigil paths
+ * skipped, write ≠ read) WITHOUT a kernel handle — unlike the opaque MCP tool
+ * args, which is why MCP writes stay in embedded mode.
+ *
+ * This module is pure request classification — no I/O, no forwarding — so it is
+ * unit-testable and the proxy transport composes it.
+ */
+/** What an incoming REST request requires of the caller's entitlement. */
+export type RouteRequirement = {
+    kind: "read";
+} | {
+    kind: "write";
+    repo: string;
+    paths: string[];
+} | {
+    kind: "destructive";
+} | {
+    kind: "unknown";
+};
+/**
+ * Classify a REST request into its policy requirement. `pathname` is the raw
+ * URL path (no query); `destination` is the `Destination` header value, needed
+ * for MOVE both-endpoints. Percent-encoded segments are decoded per-segment.
+ */
+export declare function classifyRestRequest(method: string, pathname: string, destination: string | undefined): RouteRequirement;