@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/middleware/api/auth.js

@@ -0,0 +1,105 @@
+/**
+ * `access(…)` — the one gate in front of every `/v1/api` route (go-prod spec §3.1, §3.4, §4.1). It
+ * names the caller and checks it against what the route declares, the same declaration the OpenAPI
+ * carries as `x-required-scope` / `x-capability` (the snapshot test holds the two together):
+ *
+ * - an API key (`Bearer eo_…`) — its scopes; `403 SCOPE` without the route's, and on a console-only
+ *   route (`scope: "none"`);
+ * - a console member (`X-Auth-Type: ucan` + `X-Source-Id`) — the grant's capabilities, checked
+ *   against the ROUTE's capability; `403 FORBIDDEN` without it (`console.ts` verifies the chain,
+ *   and that the invocation signs this route's `op` action, `API_ACTIONS`);
+ * - an AI app over OAuth (S7) — only on `/v1/mcp`'s in-process calls, never from a header
+ *   (`oauth.ts`): the user's live standing on the source AND the token's scopes;
+ * - `public` routes answer anyone and narrow to the source when a credential comes along;
+ * - `account` routes take a signed-in account with no source yet; `operator` an `ORACLE_ADMIN_DIDS`
+ *   invoker.
+ *
+ * Authentication failures are `401`; everything valid-but-not-allowed `403`; a source that is not
+ * the caller's is `404`, never `403` (§14). `nb.protocols` narrowing is per claim, so the routes
+ * that touch one apply it (`reachesProtocol`).
+ */
+import { Capability, covers } from "../../contracts/index.js";
+import { accountCaller, memberCaller, operatorCaller } from "./console.js";
+import { ApiError } from "./errors.js";
+import { isApiKey, keyCaller } from "./keys.js";
+import { oauthCaller } from "./oauth.js";
+import { limitCaller } from "./rate-limit.js";
+export function access(spec) {
+    const mw = async (c, next) => {
+        c.set("caller", await callerFor(c, spec));
+        await next();
+    };
+    return Object.assign(mw, { access: spec });
+}
+async function callerFor(c, spec) {
+    // Only the MCP handler's in-process mark makes an OAuth caller (`oauth.ts`); its bearer is unread.
+    const oauth = c.get("oauth");
+    if (oauth)
+        return oauthCaller(c, spec, oauth);
+    const token = bearer(c);
+    switch (spec.capability) {
+        case "account":
+            return accountCaller(c, requireUcan(c, token), spec.op);
+        case "operator":
+            return operatorCaller(c, requireUcan(c, token), spec.op);
+        case "public":
+            if (!token)
+                return { kind: "anonymous" };
+            return sourceCaller(c, spec, token);
+        default:
+            if (!token)
+                throw new ApiError("UNAUTHORIZED", "This request has no API key. Send it in the Authorization header as `Bearer <key>`; create a key in the console (Keys).");
+            return sourceCaller(c, spec, token);
+    }
+}
+async function sourceCaller(c, spec, token) {
+    const caller = isApiKey(token)
+        ? await keyCaller(await c.var.db(), c.get("config"), token, (p) => c.executionCtx.waitUntil(p))
+        : await memberCaller(c, requireUcan(c, token), sourceIdOf(c), spec.op);
+    // Counted once authenticated, BEFORE the route's own check: a caller hammering a route it may
+    // not use is still spending its source's budget.
+    await limitCaller(c, caller);
+    if (caller.kind === "key") {
+        const { scope } = spec;
+        if (scope === "none") {
+            throw new ApiError("SCOPE", "This can only be done from the Decision Console, not with an API key. Sign in to the console to do it.");
+        }
+        if (scope !== null && !caller.key.scopes.includes(scope)) {
+            throw new ApiError("SCOPE", `This API key doesn't have the ${scope} permission. Create a key with it in the console (Keys) or ask the source's owner.`, { required: scope });
+        }
+    }
+    else {
+        const cap = spec.capability;
+        // `sourceCaller` is reached only for a capability route or a `public` one.
+        if (cap !== null && isCapability(cap) && !covers(caller.capabilities, cap)) {
+            throw new ApiError("FORBIDDEN", `Your role on this source doesn't allow this (it needs the ${cap} permission). Ask the source's owner for a role that includes it.`, { required: cap });
+        }
+    }
+    return caller;
+}
+function sourceIdOf(c) {
+    const sourceId = c.req.header("X-Source-Id");
+    if (!sourceId)
+        throw new ApiError("UNAUTHORIZED", "This console request doesn't say which source it is for. Pick a source in the console and try again (developers: send its id in the X-Source-Id header).");
+    return sourceId;
+}
+const isCapability = (v) => Capability.safeParse(v).success;
+function bearer(c) {
+    const h = c.req.header("Authorization");
+    return h?.startsWith("Bearer ") ? h.slice(7).trim() || null : null;
+}
+function requireUcan(c, token) {
+    if (!token || c.req.header("X-Auth-Type") !== "ucan") {
+        throw new ApiError("UNAUTHORIZED", "This needs a Decision Console sign-in, not an API key. Sign in to the console and try again (developers: send a signed UCAN with the header X-Auth-Type: ucan).");
+    }
+    return token;
+}
+/** The caller of a source-scoped route — `access()` guarantees one. */
+export function sourceOf(c) {
+    const caller = c.get("caller");
+    if (caller.kind !== "key" && caller.kind !== "member" && caller.kind !== "oauth") {
+        throw new ApiError("UNAUTHORIZED", "This needs an API key or a console sign-in on a source.");
+    }
+    return caller;
+}
+//# sourceMappingURL=auth.js.map

package/dist/middleware/api/auth.js.map

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

package/dist/middleware/api/console.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The Decision Console's credential on `/v1/api` (go-prod spec §3.1, §3.4): a UCAN invocation the
+ * signed-in account signs DIRECTLY with its `did:ixo` key, addressed to this oracle's did:web, with
+ * ONE capability `{ with: <resource>, can: <the route's action> }` — `oracleResource` for
+ * account/operator routes, `sourceResource` (+ `X-Source-Id`) for a source's routes, carrying the
+ * member's role grant as its proof unless the invoker is a controller of the source's organisation. The action is the route's
+ * `API_ACTIONS` entry (CLAUDE.md "Capabilities: one action per route"): it says what the token is
+ * FOR; what the member may do is the grant's capability, checked by `auth.ts`. Any other `can`, the
+ * legacy `*` included, is 403.
+ *
+ * Not `@ixo/ucan`'s `validator.validate`: ucanto's `claim()` matches `can` by exact string, so it
+ * cannot say that `source/*` covers `claims/read`. This file walks the chain itself — at most two
+ * grant links (controller → member, or controller → co-owner holding `source/*` → member), one proof per link,
+ * every signature checked against a key the issuer's DID resolves to (`lib/ixo/grant-chain.ts`,
+ * shared with the chain lane's reviewer grants).
+ *
+ * Two halves, cached differently:
+ *   - the SIGNED STRUCTURE (parse, audience, signatures, links chaining) is a pure function of the
+ *     token: cached per sha256(token) in L1 + KV until the invocation's `exp` (at most 600 s), a
+ *     deterministic failure negative-cached 30 s in L1 (401), resolver trouble never cached (503) —
+ *     as ucan-auth;
+ *   - the POLICY (source, roots, times, revocations, member row) runs on EVERY request, so a revoke
+ *     is effective at once however warm the cache is. The roots are the organisation entity's
+ *     CURRENT controllers, read live (`sourceRoots`, D1/D10) — there is no personal root.
+ *
+ * A grant is identified by its CANONICAL CID — sha2-256 over its UCAN re-encoded as DAG-CBOR —
+ * and a delegation filed under any other CID is refused: ucanto's CAR decode never checks a
+ * block's hash, so the presented CID is attacker-chosen. And a member's leaf must BE their stored
+ * grant (`api_members.delegationCid`), a co-owner's link the co-owner's own live stored grant: the
+ * revocation list is a second line, never the only one.
+ *
+ * `verifyGrant` is the same chain code over an uploaded grant CAR (`PUT /members/:id/delegation`);
+ * there every refusal is the uploader's mistake, so `400 VALIDATION`.
+ */
+import { type ApiOp, Capability, type MemberRole } from "../../contracts/capabilities.js";
+import type { Database } from "../../db/client.js";
+import { type ApiSource } from "../../db/schema.js";
+import type { BlocksyncDeps } from "../../lib/ixo/blocksync/types.js";
+import type { AccountCaller, ApiContext, MemberCaller, OperatorCaller } from "./types.js";
+export { setDidResolverForTests } from "../../lib/ixo/grant-chain.js";
+/** The Blocksync deps a request reads the roots with. */
+export declare const chainOf: (c: Pick<ApiContext, "get">) => BlocksyncDeps;
+/**
+ * A console member on `sourceId` (§3.4). Anyone who is neither one of the source's roots nor has a
+ * member row on it ⇒ 404, whatever they present (§14: never 403 across sources, so a sourceId
+ * cannot be probed); a root invoking as itself ⇒ `source/*`; a member ⇒ the chain's effective
+ * grant, provided its leaf IS their stored grant, it is rooted at a root (directly, or through a
+ * co-owner whose own stored grant is live), unexpired and unrevoked — else 403. The roots are the
+ * organisation entity's current controllers (D10): a controller invoking with no proof needs no
+ * member row (G13). A former controller with no row is a stranger: 404.
+ */
+export declare function memberCaller(c: ApiContext, token: string, sourceId: string, op: ApiOp): Promise<MemberCaller>;
+/**
+ * What `did` may do on `source` NOW by its STORED grant — the OAuth caller's reading (S7), the same
+ * policy `memberCaller` applies to a presented chain: a root holds `source/*`; anyone else needs
+ * an accepted, unrevoked, unexpired member row whose stored grant (its canonical CID the row's)
+ * is rooted at a root directly or through a co-owner who is live now, with no link revoked.
+ * The CAR was verified when it was uploaded (`verifyGrant`), so only its links are read here, not
+ * its signatures. `roots` are the source's (`sourceRoots`, read live by the caller, who may share
+ * one read across a request's sources of one organisation). Null = no standing (the caller answers
+ * 404).
+ */
+export declare function storedGrant(db: Database, roots: readonly string[], oracleDid: string, source: ApiSource, did: string, now?: number): Promise<{
+    role: MemberRole;
+    capabilities: Capability[];
+    protocols: string[] | null;
+} | null>;
+/** A signed-in IXO account invoking as itself on `oracleResource` — no grant, no source. */
+export declare function accountCaller(c: ApiContext, token: string, op: ApiOp): Promise<AccountCaller>;
+/** An account invocation from one of `ORACLE_ADMIN_DIDS`. */
+export declare function operatorCaller(c: ApiContext, token: string, op: ApiOp): Promise<OperatorCaller>;
+export interface VerifiedGrant {
+    cid: string;
+    capabilities: Capability[];
+    protocols: string[] | null;
+    expiresAt: Date | null;
+    /** The CAR as uploaded. */
+    delegation: string;
+}
+/**
+ * An uploaded role grant (`PUT /members/:memberId/delegation`, §3.4 step 3): to `memberDid`, rooted
+ * at a root — a current controller of the organisation — (or a co-owner holding
+ * `source/*`), over this source's resource, capabilities
+ * EXACTLY `role`'s preset, unexpired, no link revoked. Any refusal ⇒ `400 VALIDATION`; resolver
+ * trouble ⇒ 503.
+ */
+export declare function verifyGrant(c: ApiContext, delegation: string, target: {
+    source: ApiSource;
+    memberDid: string;
+    role: MemberRole;
+}): Promise<VerifiedGrant>;
+//# sourceMappingURL=console.d.ts.map

package/dist/middleware/api/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../../src/middleware/api/console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH,OAAO,EAEL,KAAK,KAAK,EACV,UAAU,EACV,KAAK,UAAU,EAMhB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,SAAS,EAAc,MAAM,iBAAiB,CAAC;AAG7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAenE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAmCvF,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAoJnE,yDAAyD;AACzD,eAAO,MAAM,OAAO,MAAO,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,KAAG,aAGnD,CAAC;AA+DH;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,YAAY,CAAC,CA4FvB;AAKD;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,MAAM,EACX,GAAG,SAAgC,GAClC,OAAO,CAAC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,YAAY,EAAE,UAAU,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CAwB9F;AAED,4FAA4F;AAC5F,wBAAsB,aAAa,CACjC,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,aAAa,CAAC,CAwBxB;AAED,6DAA6D;AAC7D,wBAAsB,cAAc,CAClC,CAAC,EAAE,UAAU,EACb,KAAK,EAAE,MAAM,EACb,EAAE,EAAE,KAAK,GACR,OAAO,CAAC,cAAc,CAAC,CASzB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,CAAC,EAAE,UAAU,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GACjE,OAAO,CAAC,aAAa,CAAC,CAsDxB"}

package/dist/middleware/api/console.js

@@ -0,0 +1,446 @@
+/**
+ * The Decision Console's credential on `/v1/api` (go-prod spec §3.1, §3.4): a UCAN invocation the
+ * signed-in account signs DIRECTLY with its `did:ixo` key, addressed to this oracle's did:web, with
+ * ONE capability `{ with: <resource>, can: <the route's action> }` — `oracleResource` for
+ * account/operator routes, `sourceResource` (+ `X-Source-Id`) for a source's routes, carrying the
+ * member's role grant as its proof unless the invoker is a controller of the source's organisation. The action is the route's
+ * `API_ACTIONS` entry (CLAUDE.md "Capabilities: one action per route"): it says what the token is
+ * FOR; what the member may do is the grant's capability, checked by `auth.ts`. Any other `can`, the
+ * legacy `*` included, is 403.
+ *
+ * Not `@ixo/ucan`'s `validator.validate`: ucanto's `claim()` matches `can` by exact string, so it
+ * cannot say that `source/*` covers `claims/read`. This file walks the chain itself — at most two
+ * grant links (controller → member, or controller → co-owner holding `source/*` → member), one proof per link,
+ * every signature checked against a key the issuer's DID resolves to (`lib/ixo/grant-chain.ts`,
+ * shared with the chain lane's reviewer grants).
+ *
+ * Two halves, cached differently:
+ *   - the SIGNED STRUCTURE (parse, audience, signatures, links chaining) is a pure function of the
+ *     token: cached per sha256(token) in L1 + KV until the invocation's `exp` (at most 600 s), a
+ *     deterministic failure negative-cached 30 s in L1 (401), resolver trouble never cached (503) —
+ *     as ucan-auth;
+ *   - the POLICY (source, roots, times, revocations, member row) runs on EVERY request, so a revoke
+ *     is effective at once however warm the cache is. The roots are the organisation entity's
+ *     CURRENT controllers, read live (`sourceRoots`, D1/D10) — there is no personal root.
+ *
+ * A grant is identified by its CANONICAL CID — sha2-256 over its UCAN re-encoded as DAG-CBOR —
+ * and a delegation filed under any other CID is refused: ucanto's CAR decode never checks a
+ * block's hash, so the presented CID is attacker-chosen. And a member's leaf must BE their stored
+ * grant (`api_members.delegationCid`), a co-owner's link the co-owner's own live stored grant: the
+ * revocation list is a second line, never the only one.
+ *
+ * `verifyGrant` is the same chain code over an uploaded grant CAR (`PUT /members/:id/delegation`);
+ * there every refusal is the uploader's mistake, so `400 VALIDATION`.
+ */
+import { eq } from "drizzle-orm";
+import { AccountDid } from "../../contracts/api.js";
+import { API_ACTIONS, Capability, oracleResource, PROTOCOL_SCOPED, ROLE_CAPABILITIES, roleOf, sourceResource, } from "../../contracts/capabilities.js";
+import { apiSources } from "../../db/schema.js";
+import { sourceRoots } from "../../lib/api-lane/company.js";
+import { sha256Hex } from "../../lib/hash.js";
+import { decode, finite, Invalid, proofsOf as proofsUnder, Refused, summarize, verifyChain, } from "../../lib/ixo/grant-chain.js";
+import { oracleWebDid } from "../../lib/ixo/ucan.js";
+import { REVIEWER_GRANT_MAX_SEC } from "../../lib/review/reviewer-grant.js";
+import { ApiError, assertLinkedFor } from "./errors.js";
+import { anyRevoked, coOwnerLive, memberRow } from "./membership.js";
+/** Grant links in a chain, the invocation not counted (§3.4: "chains are at most two links"). */
+const MAX_LINKS = 2;
+/** Client clock drift allowed on the invocation's own `exp`/`nbf` (seconds). */
+const SKEW_SEC = 30;
+/** Deterministic-invalid tokens are negative-cached this long (as ucan-auth). */
+const NEGATIVE_TTL_SEC = 30;
+/** An invocation's longest life (§3.1, §14 "short-lived UCANs"); the console signs 120 s. */
+const MAX_LIFETIME_SEC = 600;
+/** L1 entries past this trigger a sweep of the expired ones (garbage tokens each add one). */
+const L1_MAX = 10_000;
+const KV_PREFIX = "api-ucan:";
+/** A chain deeper than MAX_LINKS: the grant must come (more) directly from the owner. */
+const passedOnTooFar = `it is passed on through more than ${MAX_LINKS} grants — an admin of the organisation (or a co-owner) must grant it directly`;
+const proofsOf = (top) => proofsUnder(top, { max: MAX_LINKS, message: passedOnTooFar });
+// Where the console tests install their DID resolver (it belongs to the chain code it fakes).
+export { setDidResolverForTests } from "../../lib/ixo/grant-chain.js";
+const l1 = new Map();
+function remember(key, entry, now) {
+    l1.set(key, entry);
+    if (l1.size > L1_MAX) {
+        for (const [k, v] of l1)
+            if (v.exp <= now)
+                l1.delete(k);
+        // A flood of fresh garbage outlives the sweep: dropping the lot only costs re-verification.
+        if (l1.size > L1_MAX)
+            l1.clear();
+    }
+}
+/** The 403's message: the request is signed, but the access it carries does not reach. */
+const accessRefused = (reason) => `Your access to this source could not be confirmed: ${reason}.`;
+/** The 401's message: what was wrong with the signed request, in words a console can show. */
+const signInRefused = (reason) => `This request's sign-in could not be verified: ${reason}.`;
+async function verifiedInvocation(c, token) {
+    const now = Math.floor(Date.now() / 1000);
+    const key = await sha256Hex(token);
+    const hit = l1.get(key);
+    if (hit && hit.exp > now) {
+        // The reason is cached with the refusal: a console retries, and a bare "invalid" on the second
+        // try leaves nobody able to tell what to fix.
+        if ("invalid" in hit)
+            throw new ApiError("UNAUTHORIZED", signInRefused(hit.invalid));
+        return hit.verified;
+    }
+    if (hit)
+        l1.delete(key);
+    const l2 = await c.env.CACHE_KV.get(`${KV_PREFIX}${key}`, "json").catch(() => null);
+    if (l2 && l2.exp > now) {
+        remember(key, { exp: Math.min(l2.exp, now + MAX_LIFETIME_SEC), verified: l2 }, now);
+        return l2;
+    }
+    const config = c.get("config");
+    let verified;
+    try {
+        verified = await verifyInvocation(config, token);
+    }
+    catch (err) {
+        if (!(err instanceof Invalid))
+            throw err;
+        remember(key, { exp: now + NEGATIVE_TTL_SEC, invalid: err.message }, now);
+        c.get("logger").warn("api.ucan.invalid", { reason: err.message });
+        throw new ApiError("UNAUTHORIZED", signInRefused(err.message));
+    }
+    // Capped at the longest life a token may have: a far-future `exp` is refused by `checkWindow`
+    // until its last MAX_LIFETIME_SEC, and its verified entry must not sit in L1/KV meanwhile.
+    const ttl = Math.min(verified.exp - now, MAX_LIFETIME_SEC);
+    remember(key, { exp: now + ttl, verified }, now);
+    if (ttl > 0) {
+        // KV's floor is 60 s; the `exp` inside the value is what a read trusts.
+        await c.env.CACHE_KV.put(`${KV_PREFIX}${key}`, JSON.stringify(verified), {
+            expirationTtl: Math.max(60, ttl),
+        }).catch(() => { });
+    }
+    return verified;
+}
+async function verifyInvocation(config, token) {
+    const inv = await decode(token);
+    const audience = oracleWebDid(config);
+    if (inv.audience.did() !== audience) {
+        throw new Invalid(`it was signed for ${inv.audience.did()}, but this oracle is ${audience} — use the id from /.well-known/did.json`);
+    }
+    const [cap, ...rest] = inv.capabilities;
+    if (!cap || rest.length > 0 || !cap.can) {
+        throw new Invalid('it must carry exactly one capability: { with: "<resource>", can: "<the route\'s action>" }');
+    }
+    const exp = finite(inv.expiration);
+    if (exp === null)
+        throw new Invalid(`it has no expiry — give it one of at most ${MAX_LIFETIME_SEC} s`);
+    // A too-deep chain is refused before anything is resolved.
+    let proofs;
+    try {
+        proofs = await proofsOf(inv);
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            throw new ApiError("FORBIDDEN", accessRefused(err.message));
+        throw err;
+    }
+    await verifyChain(config, [...proofs, inv]);
+    return {
+        invoker: inv.issuer.did(),
+        resource: cap.with,
+        can: cap.can,
+        exp,
+        nbf: finite(inv.notBefore),
+        links: await Promise.all(proofs.map(summarize)),
+    };
+}
+/** The invocation's own window — an authentication fact, so 401. */
+function checkWindow(v, now) {
+    if (v.exp + SKEW_SEC < now)
+        throw new ApiError("UNAUTHORIZED", signInRefused("it has expired — sign a fresh request (and check the device clock)"));
+    // UCAN invocations carry no issued-at, so `exp - now` alone would accept a far-future token once
+    // it is within its last MAX_LIFETIME_SEC; a stated `nbf` bounds the whole window as well.
+    if (v.exp - now > MAX_LIFETIME_SEC || (v.nbf !== null && v.exp - v.nbf > MAX_LIFETIME_SEC)) {
+        throw new ApiError("UNAUTHORIZED", signInRefused(`it is valid for too long — at most ${MAX_LIFETIME_SEC} s`));
+    }
+    if (v.nbf !== null && v.nbf - SKEW_SEC > now) {
+        throw new ApiError("UNAUTHORIZED", signInRefused("it is not valid yet — check the device clock"));
+    }
+}
+/**
+ * The invocation's `can` must be the route's action. Anything else — another route's action, `*`, or
+ * none (a cache entry from before actions) — is 403: the token is genuine, just not for this call.
+ */
+function checkAction(v, op) {
+    const action = API_ACTIONS[op];
+    if (v.can === action)
+        return;
+    throw new ApiError("FORBIDDEN", `This request was signed for "${v.can ?? "*"}", but this route takes "${action}". Reload the console and try again.`);
+}
+/** The Blocksync deps a request reads the roots with. */
+export const chainOf = (c) => ({
+    config: c.get("config"),
+    trace: c.get("trace"),
+});
+/**
+ * What a chain grants over `resource`, rooted at one of the source's `roots` (§3.4, D1). Every capability of every link
+ * must be over exactly `resource`, so a grant for another source proves nothing here. A two-link
+ * chain's middle issuer must hold `source/*` from a root, so the leaf's capabilities are the
+ * effective ones (the intersection with `source/*` is the leaf itself). Unknown `can` values grant
+ * nothing.
+ */
+function grantOf(links, roots, resource, now) {
+    const root = links[0];
+    const leaf = links.at(-1);
+    if (!root || !leaf)
+        throw new Refused("no access grant was sent");
+    if (!roots.includes(root.issuer))
+        throw new Refused("the access was not granted by a current admin (controller) of the source's organisation");
+    for (const link of links) {
+        if (link.exp !== null && link.exp < now)
+            throw new Refused("the access grant has expired — an admin of the organisation must invite you again");
+        if (link.nbf !== null && link.nbf > now)
+            throw new Refused("the access grant has not started yet — check the device clock");
+        if (link.caps.some((cap) => cap.with !== resource)) {
+            throw new Refused("the access grant is for a different source");
+        }
+    }
+    const known = (link) => link.caps.flatMap((cap) => {
+        const can = Capability.safeParse(cap.can);
+        return can.success ? [{ can: can.data, protocols: cap.protocols }] : [];
+    });
+    if (links.length === 2 && !known(root).some((cap) => cap.can === "source/*")) {
+        throw new Refused("the person who granted this access is not a co-owner of this source");
+    }
+    const capabilities = [...new Set(known(leaf).map((cap) => cap.can))];
+    if (capabilities.length === 0)
+        throw new Refused("the access grant gives no permissions this oracle knows");
+    // Per link: the union of the protocols its claims/* caps name — ANY cap that names some narrows the
+    // link (a grant never comes out wider than what was signed: a `claims/submit` limited to one
+    // protocol beside an unlimited `claims/read` still limits submitting); along the chain: the
+    // intersection of the links that narrow.
+    let protocols = null;
+    for (const link of links) {
+        const scoped = known(link).filter((cap) => PROTOCOL_SCOPED.includes(cap.can));
+        if (scoped.every((cap) => !cap.protocols))
+            continue;
+        const union = [...new Set(scoped.flatMap((cap) => cap.protocols ?? []))];
+        protocols = protocols === null ? union : protocols.filter((p) => union.includes(p));
+    }
+    const exps = links.map((l) => l.exp).filter((e) => e !== null);
+    return {
+        capabilities,
+        protocols,
+        exp: exps.length > 0 ? Math.min(...exps) : null,
+        leafCans: leaf.caps.map((cap) => cap.can),
+    };
+}
+// --- the callers -------------------------------------------------------------------------------
+/**
+ * A console member on `sourceId` (§3.4). Anyone who is neither one of the source's roots nor has a
+ * member row on it ⇒ 404, whatever they present (§14: never 403 across sources, so a sourceId
+ * cannot be probed); a root invoking as itself ⇒ `source/*`; a member ⇒ the chain's effective
+ * grant, provided its leaf IS their stored grant, it is rooted at a root (directly, or through a
+ * co-owner whose own stored grant is live), unexpired and unrevoked — else 403. The roots are the
+ * organisation entity's current controllers (D10): a controller invoking with no proof needs no
+ * member row (G13). A former controller with no row is a stranger: 404.
+ */
+export async function memberCaller(c, token, sourceId, op) {
+    const v = await verifiedInvocation(c, token);
+    const now = Math.floor(Date.now() / 1000);
+    checkWindow(v, now);
+    const db = await c.var.db();
+    // Both reads at once: a missing source and a source the caller is not in answer the same 404,
+    // and must not take measurably different times either (§14).
+    const [source, row] = await Promise.all([
+        db.query.apiSources.findFirst({ where: eq(apiSources.sourceId, sourceId) }),
+        memberRow(db, sourceId, v.invoker),
+    ]);
+    const roots = source ? await sourceRoots(chainOf(c), source) : [];
+    const isRoot = roots.includes(v.invoker);
+    if (!source || (!isRoot && !row))
+        throw new ApiError("NOT_FOUND", 
+        // The id is not echoed: the message is logged, and a pending source's id never is.
+        "This source was not found, or you are not a member of it. Check that you are signed in with the right account.");
+    const resource = sourceResource(oracleWebDid(c.get("config")), sourceId);
+    if (v.resource !== resource)
+        throw new ApiError("FORBIDDEN", "This request was signed for a different source than the one it names. Reload the console and try again.");
+    // After the 404: a non-member learns nothing about the source from the action's refusal.
+    checkAction(v, op);
+    // D10: once, here, for every console route — the few a source that is not linked still answers
+    // (lists, me, the sync and the ways out) are the helper's.
+    assertLinkedFor(source, op);
+    if (isRoot && v.links.length === 0) {
+        return {
+            kind: "member",
+            source,
+            did: v.invoker,
+            controller: true,
+            memberId: row?.memberId ?? null,
+            role: "owner",
+            capabilities: ["source/*"],
+            protocols: null,
+        };
+    }
+    if (!row?.acceptedAt)
+        throw new ApiError("FORBIDDEN", "You were invited to this source but haven't accepted the invitation yet. Open the invitation link to accept it, then try again.");
+    if (row.revokedAt)
+        throw new ApiError("FORBIDDEN", "You're no longer a member of this source — ask an admin of its organisation to invite you again.");
+    if (v.links.length === 0)
+        throw new ApiError("FORBIDDEN", "This request didn't include your access to this source. Reload the console so it picks up your access, then try again.");
+    // The schema's rule: a member without a stored grant can call nothing.
+    if (!row.delegationCid || v.links.at(-1)?.cid !== row.delegationCid) {
+        throw new ApiError("FORBIDDEN", "Your access to this source has changed since you signed in. Reload the console to pick up your current access.");
+    }
+    let grant;
+    try {
+        grant = grantOf(v.links, roots, resource, now);
+        if (!(await coOwnerLive(db, sourceId, v.links, now)))
+            throw new Refused(coOwnerGone);
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            throw new ApiError("FORBIDDEN", accessRefused(err.message));
+        throw err;
+    }
+    if (await anyRevoked(db, sourceId, v.links)) {
+        throw new ApiError("FORBIDDEN", "Your access to this source has been revoked — ask an admin of its organisation to invite you again.");
+    }
+    return {
+        kind: "member",
+        source,
+        did: v.invoker,
+        controller: false,
+        memberId: row.memberId,
+        role: row.role,
+        capabilities: grant.capabilities,
+        protocols: grant.protocols,
+    };
+}
+const coOwnerGone = "the co-owner who granted this access no longer has owner access — an admin of the organisation must invite you again";
+/**
+ * What `did` may do on `source` NOW by its STORED grant — the OAuth caller's reading (S7), the same
+ * policy `memberCaller` applies to a presented chain: a root holds `source/*`; anyone else needs
+ * an accepted, unrevoked, unexpired member row whose stored grant (its canonical CID the row's)
+ * is rooted at a root directly or through a co-owner who is live now, with no link revoked.
+ * The CAR was verified when it was uploaded (`verifyGrant`), so only its links are read here, not
+ * its signatures. `roots` are the source's (`sourceRoots`, read live by the caller, who may share
+ * one read across a request's sources of one organisation). Null = no standing (the caller answers
+ * 404).
+ */
+export async function storedGrant(db, roots, oracleDid, source, did, now = Math.floor(Date.now() / 1000)) {
+    if (roots.includes(did))
+        return { role: "owner", capabilities: ["source/*"], protocols: null };
+    const row = await memberRow(db, source.sourceId, did);
+    if (!row?.acceptedAt || row.revokedAt || !row.delegation || !row.delegationCid)
+        return null;
+    if (row.expiresAt && row.expiresAt.getTime() <= now * 1000)
+        return null;
+    let links;
+    try {
+        const leaf = await decode(row.delegation);
+        links = await Promise.all([...(await proofsOf(leaf)), leaf].map(summarize));
+    }
+    catch (err) {
+        if (err instanceof Invalid || err instanceof Refused)
+            return null;
+        throw err;
+    }
+    if (links.at(-1)?.cid !== row.delegationCid)
+        return null;
+    let grant;
+    try {
+        grant = grantOf(links, roots, sourceResource(oracleDid, source.sourceId), now);
+    }
+    catch (err) {
+        if (err instanceof Refused)
+            return null;
+        throw err;
+    }
+    if (!(await coOwnerLive(db, source.sourceId, links, now)))
+        return null;
+    if (await anyRevoked(db, source.sourceId, links))
+        return null;
+    return { role: row.role, capabilities: grant.capabilities, protocols: grant.protocols };
+}
+/** A signed-in IXO account invoking as itself on `oracleResource` — no grant, no source. */
+export async function accountCaller(c, token, op) {
+    const v = await verifiedInvocation(c, token);
+    checkWindow(v, Math.floor(Date.now() / 1000));
+    if (v.links.length > 0) {
+        throw new ApiError("FORBIDDEN", "Account requests are signed by your own account alone, without a source's access attached. Reload the console and try again.");
+    }
+    const expected = oracleResource(oracleWebDid(c.get("config")));
+    if (v.resource !== expected) {
+        throw new ApiError("FORBIDDEN", `This request was signed for ${v.resource}, but account requests must be signed for ${expected}. Reload the console and try again.`);
+    }
+    checkAction(v, op);
+    if (!AccountDid.safeParse(v.invoker).success) {
+        throw new ApiError("FORBIDDEN", `Only IXO accounts (did:ixo:…) can do this, and ${v.invoker} is not one. Sign in to the console with your IXO account.`);
+    }
+    return { kind: "account", did: v.invoker };
+}
+/** An account invocation from one of `ORACLE_ADMIN_DIDS`. */
+export async function operatorCaller(c, token, op) {
+    const { did } = await accountCaller(c, token, op);
+    if (!c.get("config").ORACLE_ADMIN_DIDS.includes(did)) {
+        throw new ApiError("FORBIDDEN", "Only this oracle's operators can do this, and your account is not one of them.");
+    }
+    return { kind: "operator", did };
+}
+/**
+ * An uploaded role grant (`PUT /members/:memberId/delegation`, §3.4 step 3): to `memberDid`, rooted
+ * at a root — a current controller of the organisation — (or a co-owner holding
+ * `source/*`), over this source's resource, capabilities
+ * EXACTLY `role`'s preset, unexpired, no link revoked. Any refusal ⇒ `400 VALIDATION`; resolver
+ * trouble ⇒ 503.
+ */
+export async function verifyGrant(c, delegation, target) {
+    const { source } = target;
+    const config = c.get("config");
+    const resource = sourceResource(oracleWebDid(config), source.sourceId);
+    const now = Math.floor(Date.now() / 1000);
+    try {
+        const leaf = await decode(delegation);
+        if (leaf.audience.did() !== target.memberDid) {
+            throw new Refused("it is issued to a different account than this member's");
+        }
+        const chain = [...(await proofsOf(leaf)), leaf];
+        if (chain.length > MAX_LINKS)
+            throw new Refused(passedOnTooFar);
+        await verifyChain(config, chain);
+        const links = await Promise.all(chain.map(summarize));
+        const grant = grantOf(links, await sourceRoots(chainOf(c), source), resource, now);
+        const unknown = grant.leafCans.filter((can) => !Capability.safeParse(can).success);
+        if (unknown.length > 0 || roleOf(grant.capabilities) !== target.role) {
+            throw new Refused(`it must give exactly the ${target.role} role's permissions (${ROLE_CAPABILITIES[target.role].join(", ")})`);
+        }
+        // A grant that reviews is the first link of every answer's `reviewerGrant`, which the engine
+        // holds to its window (lib/review/reviewer-grant.ts `parseMemberReviewGrant`): refuse one that
+        // could never stand there now, not at the member's first answer.
+        const leafLink = links.at(-1);
+        if (leafLink.caps.some((cap) => cap.can === "claims/review") &&
+            (leafLink.nbf === null ||
+                leafLink.exp === null ||
+                leafLink.exp - leafLink.nbf > REVIEWER_GRANT_MAX_SEC)) {
+            throw new Refused(`reviewer grants last at most ${REVIEWER_GRANT_MAX_SEC / 86_400} days, with a start (nbf) and an end (exp) — re-grant this role with a window of 30 days or less`);
+        }
+        const db = await c.var.db();
+        if (!(await coOwnerLive(db, source.sourceId, links, now)))
+            throw new Refused(coOwnerGone);
+        if (await anyRevoked(db, source.sourceId, links)) {
+            throw new Refused("it (or the grant it builds on) has been revoked");
+        }
+        return {
+            // Canonical (`summarize`): what the row stores, `memberCaller` binds and a revoke lists.
+            cid: links.at(-1).cid,
+            capabilities: grant.capabilities,
+            protocols: grant.protocols,
+            expiresAt: grant.exp === null ? null : new Date(grant.exp * 1000),
+            delegation,
+        };
+    }
+    catch (err) {
+        if (err instanceof Invalid || err instanceof Refused) {
+            throw new ApiError("VALIDATION", `This role grant can't be accepted: ${err.message}.`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=console.js.map