@waterlock/gateway 0.0.0-stage → 0.1.1

package/dist/core/evaluate.d.ts

@@ -0,0 +1,41 @@
+import type { AnyRequest, Policy } from "./policy.js";
+import type { SessionStore } from "./store.js";
+/**
+ * Answers one natural-language `when` condition. You write it: call the AI SDK (or anything)
+ * however you like. Helpers for the prompt and output schema live in `@waterlock/gateway/checks`.
+ */
+export type Check<R extends AnyRequest = AnyRequest> = (input: {
+    condition: string;
+    request: R;
+    /**
+     * The gateway's session store (if configured). Read context from it, e.g. user messages
+     * for `request.session`. `checkPrompt` does this for you.
+     */
+    store?: SessionStore;
+    /** Aborted once the decision is made elsewhere. Pass it on, e.g. `generateText({ abortSignal: signal })`. */
+    signal: AbortSignal;
+}) => Promise<{
+    result: boolean;
+    explanation?: string;
+}>;
+export interface CheckOptions<R extends AnyRequest = AnyRequest> {
+    check?: Check<R>;
+    /** Per-check timeout. Default 60s. */
+    checkTimeoutMs?: number;
+}
+export interface Decision {
+    /** May gain members later (e.g. "approve"): treat unknown values as deny. */
+    effect: "allow" | "deny";
+    /** Rules that decided the outcome, as `#<index>`. */
+    rules: string[];
+    reason: string;
+}
+/**
+ * 1. Function rules run (sync). Any error or non-boolean denies.
+ * 2. A function deny rule matched       -> deny (its reason). No checks run.
+ * 3. No allow rule matched              -> deny (allow-rule reasons as hints). No checks run.
+ * 4. Policy has no natural-language rows -> allow (nothing left to ask a model).
+ * 5. Natural-language deny rules run in parallel. The first `true` denies and aborts the rest;
+ *    all `false` allows. Errors, timeouts and malformed answers deny.
+ */
+export declare function evaluatePolicy<R extends AnyRequest>(policy: Policy<R>, req: R, opts?: CheckOptions<R>): Promise<Decision>;

package/dist/core/evaluate.js

@@ -0,0 +1,99 @@
+/**
+ * 1. Function rules run (sync). Any error or non-boolean denies.
+ * 2. A function deny rule matched       -> deny (its reason). No checks run.
+ * 3. No allow rule matched              -> deny (allow-rule reasons as hints). No checks run.
+ * 4. Policy has no natural-language rows -> allow (nothing left to ask a model).
+ * 5. Natural-language deny rules run in parallel. The first `true` denies and aborts the rest;
+ *    all `false` allows. Errors, timeouts and malformed answers deny.
+ */
+export async function evaluatePolicy(policy, req, opts = {}) {
+    const rules = policy.rules.map((rule, i) => ({ id: `#${i}`, rule, action: rule.action ?? "allow" }));
+    const deny = (ids, reason) => ({ effect: "deny", rules: ids, reason });
+    const input = Object.freeze({ ...req }); // rules can't mutate what later rules see
+    const matched = [];
+    for (const r of rules) {
+        if (typeof r.rule.when !== "function")
+            continue;
+        let value;
+        try {
+            value = r.rule.when(input);
+        }
+        catch (err) {
+            return deny([r.id], `rule ${r.id} threw: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (typeof value !== "boolean")
+            return deny([r.id], `rule ${r.id} returned ${describe(value)}, expected boolean`);
+        if (value)
+            matched.push(r);
+    }
+    const staticDeny = matched.find((r) => r.action === "deny");
+    if (staticDeny)
+        return deny([staticDeny.id], staticDeny.rule.reason ?? `denied by ${staticDeny.id}`);
+    const allowed = matched.filter((r) => r.action === "allow");
+    if (!allowed.length) {
+        const hints = rules.filter((r) => r.action === "allow" && r.rule.reason).map((r) => r.rule.reason);
+        return deny([], hints.length ? hints.join(" ") : "no allow rule matched");
+    }
+    const dynamic = rules.filter((r) => typeof r.rule.when === "string");
+    const allow = {
+        effect: "allow",
+        rules: allowed.map((r) => r.id),
+        reason: `allowed by ${allowed.map((r) => r.id).join(", ")}`,
+    };
+    if (!dynamic.length)
+        return allow;
+    return runChecks(dynamic, req, opts, allow);
+}
+async function runChecks(dynamic, request, opts, allow) {
+    const check = opts.check;
+    if (!check)
+        return { effect: "deny", rules: [], reason: "policy has natural-language rules but the gateway has no check function" };
+    const timeoutMs = opts.checkTimeoutMs ?? 60_000;
+    const controller = new AbortController();
+    const asked = new Map(); // same condition in two rows runs once
+    const ask = (condition) => {
+        let p = asked.get(condition);
+        if (!p) {
+            p = withTimeout(check({ condition, request, signal: controller.signal }), timeoutMs).then((out) => {
+                const o = out;
+                if (typeof o?.result !== "boolean")
+                    throw new Error("returned a malformed result");
+                return { result: o.result, ...(typeof o.explanation === "string" ? { explanation: o.explanation } : {}) };
+            });
+            asked.set(condition, p);
+        }
+        return p;
+    };
+    return new Promise((resolve) => {
+        let remaining = dynamic.length;
+        let settled = false;
+        const settle = (d) => {
+            if (settled)
+                return;
+            settled = true;
+            controller.abort();
+            resolve(d);
+        };
+        for (const { id, rule } of dynamic) {
+            const condition = rule.when;
+            ask(condition).then((record) => {
+                if (record.result)
+                    settle({ ...allow, effect: "deny", rules: [id], reason: rule.reason ?? record.explanation ?? `denied by ${id}` });
+                else if (--remaining === 0)
+                    settle(allow);
+            }, (err) => settle({ ...allow, effect: "deny", rules: [id], reason: `check "${condition}" failed: ${err instanceof Error ? err.message : String(err)}` }));
+        }
+    });
+}
+function withTimeout(p, ms) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+    });
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+function describe(v) {
+    if (v instanceof Promise || (typeof v === "object" && v !== null && "then" in v))
+        return "a Promise (rules must be sync)";
+    return v === null ? "null" : typeof v;
+}

package/dist/core/gateway.d.ts

@@ -0,0 +1,21 @@
+import { type Check } from "./evaluate.js";
+import { type Policy, type PolicyRule } from "./policy.js";
+import type { ProviderDefinition, RequestOf } from "./provider.js";
+import type { Sessions } from "./session.js";
+export interface GatewayOptions<P extends readonly ProviderDefinition[]> {
+    providers: P;
+    /**
+     * `definePolicy(...)` result, or the rules array inline (typed from `providers`, no type argument).
+     * Must cover every provider's requests: a Gmail-only policy on a Gmail + GitHub gateway won't compile.
+     */
+    policy: Policy<RequestOf<P>> | PolicyRule<RequestOf<P>>[];
+    sessions: Sessions;
+    /** Answers plain-language `when` rows, e.g. with your own AI SDK call. Absent = those rows deny. */
+    check?: Check<RequestOf<P>>;
+    /** Per-check timeout. Default 60s. */
+    checkTimeoutMs?: number;
+    maxBodyBytes?: number;
+}
+export declare function createGateway<const P extends readonly ProviderDefinition[]>(opts: GatewayOptions<P>): {
+    fetch: (req: Request) => Promise<Response>;
+};

package/dist/core/gateway.js

@@ -0,0 +1,152 @@
+import { createMatcher } from "./match.js";
+import { evaluatePolicy } from "./evaluate.js";
+import { definePolicy } from "./policy.js";
+/** Only these request headers reach upstream. Everything else (cookies, method overrides, the session token) is dropped. */
+const FORWARD_REQUEST_HEADERS = ["accept", "accept-language", "content-type", "if-match", "if-none-match", "user-agent", "x-goog-api-client"];
+/** Some APIs honor these and would let a POST act as a DELETE. Reject outright. */
+const METHOD_OVERRIDE_HEADERS = ["x-http-method-override", "x-http-method", "x-method-override"];
+const DROP_RESPONSE_HEADERS = ["set-cookie", "content-encoding", "content-length", "transfer-encoding", "connection", "keep-alive"];
+export function createGateway(opts) {
+    const policy = Array.isArray(opts.policy) ? definePolicy(opts.policy) : opts.policy;
+    const maxBody = opts.maxBodyBytes ?? 10 * 1024 * 1024;
+    const ids = opts.providers.map((p) => p.id);
+    const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (dup)
+        throw new Error(`provider "${dup}" is configured twice`);
+    const providers = new Map(opts.providers.map((p) => [
+        p.id,
+        {
+            def: p,
+            matcher: createMatcher(p.table, { allowedGlobalQueryParams: p.allowedGlobalQueryParams }),
+        },
+    ]));
+    async function handle(req) {
+        const url = new URL(req.url);
+        const method = req.method.toUpperCase();
+        // 1. Authenticate. The signed token names the provider; the agent can't pick another.
+        const auth = await authenticate(req, opts.sessions);
+        if ("error" in auth) {
+            return fail(401, "unauthenticated", "missing or invalid session token");
+        }
+        const session = auth.claims;
+        const entry = providers.get(session.provider);
+        if (!entry)
+            return fail(403, "unknown_provider", `this gateway has no provider "${session.provider}"`);
+        // The upstream host is fixed by config; the path is forwarded as-is.
+        const upstreamPath = url.pathname;
+        const override = METHOD_OVERRIDE_HEADERS.find((h) => req.headers.has(h));
+        if (override)
+            return fail(400, "bad_request", `header ${override} not allowed`);
+        // 2. Match against the generated operation table.
+        const matched = entry.matcher.match(method, upstreamPath, url.searchParams);
+        if (!matched.ok)
+            return fail(matched.status, "policy_denied", matched.reason);
+        const { op } = matched;
+        // 3. Read body once: decode it for policy, forward the same bytes.
+        const body = await readBody(req, maxBody);
+        if (body === "too_large")
+            return fail(413, "bad_request", "body too large");
+        let context = {};
+        const decoder = entry.def.decoders?.[op.action];
+        if (decoder) {
+            if (op.variant !== "standard") {
+                const reason = `${op.variant} route for ${op.action} not supported: body can't be inspected`;
+                return deny(op.action, [], reason);
+            }
+            try {
+                context = await decoder({ body, contentType: req.headers.get("content-type") });
+            }
+            catch (err) {
+                const reason = `could not decode request body: ${err instanceof Error ? err.message : String(err)}`;
+                return deny(op.action, [], reason);
+            }
+        }
+        // Built from the provider's own table and decoder, so it matches that provider's request type.
+        const policyReq = {
+            provider: entry.def.id,
+            action: op.action,
+            params: matched.params,
+            context,
+            session,
+        };
+        // 4. Policy.
+        const decision = await evaluatePolicy(policy, policyReq, {
+            ...(opts.check
+                ? { check: (input) => opts.check({ ...input, ...(opts.sessions.store ? { store: opts.sessions.store } : {}) }) }
+                : {}),
+            ...(opts.checkTimeoutMs ? { checkTimeoutMs: opts.checkTimeoutMs } : {}),
+        });
+        if (decision.effect === "deny") {
+            return deny(op.action, decision.rules, decision.reason);
+        }
+        // 5. Forward with the real credential.
+        const headers = new Headers();
+        for (const h of FORWARD_REQUEST_HEADERS) {
+            const v = req.headers.get(h);
+            if (v !== null)
+                headers.set(h, v);
+        }
+        let credential;
+        try {
+            credential = await entry.def.credentials({ session });
+        }
+        catch {
+            return fail(502, "upstream_auth", "could not obtain upstream credential", op.action);
+        }
+        (entry.def.inject ?? bearer)({ headers, credential });
+        const upstreamUrl = entry.def.upstream.replace(/\/$/, "") + upstreamPath + url.search;
+        let upstream;
+        try {
+            upstream = await fetch(upstreamUrl, {
+                method,
+                headers,
+                body: body.length > 0 && method !== "GET" ? body : undefined,
+                redirect: "manual",
+            });
+        }
+        catch {
+            return fail(502, "upstream_unreachable", "upstream request failed", op.action);
+        }
+        const resHeaders = new Headers(upstream.headers);
+        for (const h of DROP_RESPONSE_HEADERS)
+            resHeaders.delete(h);
+        return new Response(upstream.body, { status: upstream.status, headers: resHeaders });
+    }
+    return { fetch: handle };
+}
+async function authenticate(req, sessions) {
+    const header = req.headers.get("authorization");
+    const token = header?.match(/^Bearer (\S+)$/i)?.[1];
+    return token ? sessions.verify({ token }) : { error: "missing" };
+}
+async function readBody(req, max) {
+    const declared = Number(req.headers.get("content-length") ?? 0);
+    if (declared > max)
+        return "too_large";
+    if (!req.body)
+        return new Uint8Array();
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req.body) {
+        size += chunk.length;
+        if (size > max)
+            return "too_large";
+        chunks.push(chunk);
+    }
+    const out = new Uint8Array(size);
+    let off = 0;
+    for (const c of chunks) {
+        out.set(c, off);
+        off += c.length;
+    }
+    return out;
+}
+function bearer({ headers, credential }) {
+    headers.set("authorization", `Bearer ${credential.token}`);
+}
+function deny(action, rules, reason) {
+    return fail(403, "policy_denied", reason, action, rules);
+}
+function fail(status, code, message, action, rules) {
+    return Response.json({ error: { code, message, ...(action ? { action } : {}), ...(rules?.length ? { rules } : {}) } }, { status });
+}

package/dist/core/match.d.ts

@@ -0,0 +1,16 @@
+import type { Operation, OperationTable } from "./types.js";
+export type MatchResult = {
+    ok: true;
+    op: Operation;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    status: 400 | 404 | 405;
+    reason: string;
+};
+export interface Matcher {
+    match(method: string, path: string, query: URLSearchParams): MatchResult;
+}
+export declare function createMatcher(table: OperationTable, opts: {
+    allowedGlobalQueryParams: readonly string[];
+}): Matcher;

package/dist/core/match.js

@@ -0,0 +1,97 @@
+/**
+ * Paths the upstream might interpret differently than we do. Rejected rather
+ * than normalized: whatever we match must be exactly what we forward.
+ * (WHATWG URL parsing already resolves `.`/`..` segments before we see the path.)
+ */
+const AMBIGUOUS_PATH = /\/\/|%2f|%5c|\\|%00|%2e/i;
+export function createMatcher(table, opts) {
+    const compiled = table.operations.map(compileOp);
+    const allowedGlobals = new Set(opts.allowedGlobalQueryParams);
+    return { match };
+    function match(method, path, query) {
+        if (AMBIGUOUS_PATH.test(path))
+            return { ok: false, status: 400, reason: "ambiguous path encoding" };
+        const byPath = compiled.filter((c) => c.re.test(path));
+        if (byPath.length === 0)
+            return { ok: false, status: 404, reason: `no ${table.provider} operation matches path` };
+        const candidates = byPath.filter((c) => c.op.method === method);
+        if (candidates.length === 0)
+            return { ok: false, status: 405, reason: `method ${method} not allowed on path` };
+        // Prefer the most specific template: `/messages/send` beats `/messages/{id}`.
+        candidates.sort((a, b) => b.literalChars - a.literalChars);
+        const best = candidates[0];
+        const tie = candidates.find((c) => c !== best && c.literalChars === best.literalChars && c.op.action !== best.op.action);
+        if (tie)
+            return { ok: false, status: 400, reason: `ambiguous route: ${best.op.action} vs ${tie.op.action}` };
+        const params = {};
+        const m = best.re.exec(path);
+        for (let i = 0; i < best.names.length; i++) {
+            const spec = best.op.params.find((p) => p.in === "path" && p.name === best.names[i]);
+            let raw;
+            try {
+                raw = decodeURIComponent(m[i + 1]);
+            }
+            catch {
+                return { ok: false, status: 400, reason: `bad encoding in path param ${spec.name}` };
+            }
+            const v = coerce(spec, raw);
+            if (!v.ok)
+                return { ok: false, status: 400, reason: v.reason };
+            params[spec.name] = v.value;
+        }
+        for (const key of new Set(query.keys())) {
+            const spec = best.op.params.find((p) => p.in === "query" && p.name === key);
+            if (!spec) {
+                if (allowedGlobals.has(key))
+                    continue;
+                return { ok: false, status: 400, reason: `query param "${key}" not allowed for ${best.op.action}` };
+            }
+            const values = query.getAll(key);
+            if (!spec.repeated && values.length > 1) {
+                return { ok: false, status: 400, reason: `query param "${key}" given ${values.length} times` };
+            }
+            const parsed = [];
+            for (const raw of values) {
+                const v = coerce(spec, raw);
+                if (!v.ok)
+                    return { ok: false, status: 400, reason: v.reason };
+                parsed.push(v.value);
+            }
+            params[key] = spec.repeated ? parsed : parsed[0];
+        }
+        const missing = best.op.params.find((p) => p.in === "query" && p.required && !(p.name in params));
+        if (missing)
+            return { ok: false, status: 400, reason: `missing required query param "${missing.name}"` };
+        return { ok: true, op: best.op, params };
+    }
+}
+function compileOp(op) {
+    const names = [];
+    let literalChars = 0;
+    const pattern = op.path.replace(/\{(\+?)([^}]+)\}|[^{]+/g, (whole, plus, name) => {
+        if (name === undefined) {
+            literalChars += whole.length;
+            return whole.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+        names.push(name);
+        return plus ? "(.+)" : "([^/]+)";
+    });
+    return { op, re: new RegExp(`^${pattern}$`), names, literalChars };
+}
+function coerce(spec, raw) {
+    const bad = (what) => ({ ok: false, reason: `param "${spec.name}" ${what}` });
+    if (spec.enum && !spec.enum.includes(raw))
+        return bad(`must be one of ${spec.enum.join(", ")}`);
+    switch (spec.type) {
+        case "integer":
+            return /^-?\d+$/.test(raw) ? { ok: true, value: Number(raw) } : bad("must be an integer");
+        case "number": {
+            const n = Number(raw);
+            return raw.trim() !== "" && Number.isFinite(n) ? { ok: true, value: n } : bad("must be a number");
+        }
+        case "boolean":
+            return raw === "true" || raw === "false" ? { ok: true, value: raw === "true" } : bad("must be true or false");
+        case "string":
+            return { ok: true, value: raw };
+    }
+}

package/dist/core/policy.d.ts

@@ -0,0 +1,42 @@
+import type { SessionClaims } from "./session.js";
+/** What a rule sees. Providers narrow this with literal action/param types (autocomplete only). */
+export interface ProviderRequest<P extends string = string, A extends string = string, Params extends object = object, Ctx extends object = object> {
+    provider: P;
+    action: A;
+    /** Typed path + query params, parsed by the matcher. */
+    params: Params;
+    /** Fields extracted from the body by a provider decoder (e.g. Gmail recipients). */
+    context: Ctx;
+    session: SessionClaims;
+}
+export type AnyRequest = ProviderRequest;
+/**
+ * One policy row. `when` is either:
+ *   - a sync function over the request (static), allow or deny, or
+ *   - a plain-language condition answered by the gateway's `check` (e.g. an LLM). These
+ *     rows can only deny: a model can narrow what's allowed, never grant it.
+ */
+export type PolicyRule<R extends AnyRequest = AnyRequest> = {
+    when: (r: R) => boolean;
+    /** Effect when the rule matches. Default "allow". May gain members later (e.g. "approve"). */
+    action?: "allow" | "deny";
+    /** Context for the calling agent when this rule decides the outcome. */
+    reason?: string;
+} | {
+    /** e.g. "The email contains billing information" */
+    when: string;
+    action: "deny";
+    /** Shown to the agent on deny. Default: the check's explanation. */
+    reason?: string;
+};
+export interface Policy<R extends AnyRequest = AnyRequest> {
+    readonly rules: readonly PolicyRule<R>[];
+}
+/**
+ * A policy is a list of rows. The gateway evaluates it:
+ *   - any matching "deny" row          -> deny
+ *   - no matching "allow" row          -> deny (default deny)
+ *   - otherwise                        -> allow
+ * Plain-language rows only run once the function rows would allow.
+ */
+export declare function definePolicy<R extends AnyRequest = AnyRequest>(rules: PolicyRule<R>[]): Policy<R>;

package/dist/core/policy.js

@@ -0,0 +1,10 @@
+/**
+ * A policy is a list of rows. The gateway evaluates it:
+ *   - any matching "deny" row          -> deny
+ *   - no matching "allow" row          -> deny (default deny)
+ *   - otherwise                        -> allow
+ * Plain-language rows only run once the function rows would allow.
+ */
+export function definePolicy(rules) {
+    return { rules: Object.freeze([...rules]) };
+}

package/dist/core/provider.d.ts

@@ -0,0 +1,50 @@
+import type { Credential, CredentialSource } from "./credentials.js";
+import type { AnyRequest } from "./policy.js";
+import type { OperationTable } from "./types.js";
+/**
+ * Extracts policy-relevant fields from a request body. Throwing denies the
+ * request: if the gateway can't read what a call does, it doesn't forward it.
+ */
+export type Decoder = (input: {
+    body: Uint8Array;
+    contentType: string | null;
+}) => object | Promise<object>;
+/** `R` is the request type rules see for this provider. Type-only: drives policy autocomplete and checks. */
+export interface ProviderDefinition<R extends AnyRequest = AnyRequest> {
+    id: string;
+    /** Fixed upstream origin. The harness can never choose the host. */
+    upstream: string;
+    table: OperationTable;
+    /** Spec-level query params (e.g. Google's `fields`, `alt`) allowed on every call. Anything else unlisted is denied. */
+    allowedGlobalQueryParams: readonly string[];
+    /** Per-action body decoders. Only run on the standard route; upload variants of decoded actions are denied. */
+    decoders?: Partial<Record<string, Decoder>>;
+    credentials: CredentialSource;
+    /** Default: `Authorization: Bearer <token>`. */
+    inject?: (input: {
+        headers: Headers;
+        credential: Credential;
+    }) => void;
+    /** Type-only marker, never set at runtime. */
+    readonly __request?: R;
+}
+/**
+ * Typed helper for provider definitions. Use it for custom providers too: methods added
+ * later (e.g. `withGroups`) arrive here without changing your provider code.
+ *
+ * TODO(groups): named sets of actions, usable in rules as `r.in("gmail:send")`.
+ *
+ *   withGroups<const M extends Record<string, readonly (R["action"] | `${string}*${string}`)[]>>(
+ *     groups: M,
+ *   ): Provider<R & { groups: readonly `${R["provider"]}:${keyof M & string}`[] }>;
+ *
+ *   - returns a new provider; names are prefixed with the provider id (`gmail:risky`)
+ *   - values are action names or globs (`*` one dotted segment, `**` any number)
+ *   - throw on a pattern matching no action and on invalid names; adding to an existing group extends it
+ *   - gateway: build action -> groups once per provider, set `request.groups`
+ *   - rules: `in(group)` on the rule input, typed from `groups` so typos fail typecheck
+ *   - built-in providers ship curated defaults (gmail: read, compose, send, delete, forwarding...)
+ */
+export declare function createProvider<R extends AnyRequest>(def: ProviderDefinition<R>): ProviderDefinition<R>;
+/** Union of the request types of a list of providers. */
+export type RequestOf<P extends readonly ProviderDefinition[]> = P[number] extends infer D ? D extends ProviderDefinition<infer R> ? R : never : never;

package/dist/core/provider.js

@@ -0,0 +1,20 @@
+/**
+ * Typed helper for provider definitions. Use it for custom providers too: methods added
+ * later (e.g. `withGroups`) arrive here without changing your provider code.
+ *
+ * TODO(groups): named sets of actions, usable in rules as `r.in("gmail:send")`.
+ *
+ *   withGroups<const M extends Record<string, readonly (R["action"] | `${string}*${string}`)[]>>(
+ *     groups: M,
+ *   ): Provider<R & { groups: readonly `${R["provider"]}:${keyof M & string}`[] }>;
+ *
+ *   - returns a new provider; names are prefixed with the provider id (`gmail:risky`)
+ *   - values are action names or globs (`*` one dotted segment, `**` any number)
+ *   - throw on a pattern matching no action and on invalid names; adding to an existing group extends it
+ *   - gateway: build action -> groups once per provider, set `request.groups`
+ *   - rules: `in(group)` on the rule input, typed from `groups` so typos fail typecheck
+ *   - built-in providers ship curated defaults (gmail: read, compose, send, delete, forwarding...)
+ */
+export function createProvider(def) {
+    return def;
+}

package/dist/core/session.d.ts

@@ -0,0 +1,59 @@
+import type { SessionRef, SessionStore, UserMessage } from "./store.js";
+/**
+ * Session tokens: the only credential the harness ever holds.
+ * Format: `as1.<base64url(claims)>.<base64url(hmac-sha256)>`. HMAC via WebCrypto
+ * (constant-time verify). Base64 via Buffer: Node/Bun/Deno, Workers need nodejs_compat.
+ */
+export interface SessionClaims {
+    sid: string;
+    /** Provider id this token is for. The gateway routes by it, so paths may collide across providers. */
+    provider: string;
+    agent: string;
+    onBehalfOf: string;
+    /** Task the session was minted for. Set by the trusted launcher, not the agent. */
+    intent?: string;
+    iat: number;
+    exp: number;
+}
+export interface MintInput {
+    /** Provider id this token is for, e.g. `gmail`. One token per provider. */
+    provider: string;
+    /**
+     * Reuse an existing session id, e.g. to issue a second provider's token for the same session
+     * so both share one store entry (user messages). Default: a new id.
+     */
+    sid?: string;
+    agent: string;
+    onBehalfOf: string;
+    intent?: string;
+    ttlSeconds?: number;
+}
+/** Why a token was rejected. May gain members later (e.g. "revoked"). */
+export type VerifyError = "malformed" | "bad_signature" | "expired";
+export interface Sessions {
+    mint(input: MintInput): Promise<{
+        token: string;
+        claims: SessionClaims;
+    }>;
+    verify(input: {
+        token: string;
+    }): Promise<{
+        claims: SessionClaims;
+    } | {
+        error: VerifyError;
+    }>;
+    /** The configured store, if any. */
+    readonly store: SessionStore | undefined;
+    /** Trusted code only: record what the human said. Throws if the store can't hold messages. */
+    addUserMessage(input: {
+        session: SessionRef;
+        message: UserMessage;
+    }): Promise<void>;
+}
+export declare function createSessions(opts: {
+    signingKey: string | Uint8Array;
+    defaultTtlSeconds?: number;
+    now?: () => number;
+    /** Optional storage: `memoryStore()`, your own adapter, or omit for stateless tokens. */
+    store?: SessionStore;
+}): Sessions;