@cotal-ai/auth 0.0.0 → 0.11.0

package/dist/login.js

@@ -0,0 +1,338 @@
+/**
+ * `cotal login` client — device-authorization sign-in (RFC 8628) plus the machine-local IdP
+ * session cache (plan §"How it lands in today's code" → Client).
+ *
+ * Flow: ask the IdP for a device code, show the human a verification URL + user code, poll until
+ * the sign-in is approved in a browser. What comes back — and the ONLY thing ever cached — is the
+ * IdP SESSION token. The short-lived IdP JWT the bridge exchanges is fetched fresh from `/token`
+ * per use ({@link fetchIdpJwt}): caching the JWT would let a revoked session keep minting mesh
+ * access until the JWT expired, so instead revocation at the IdP bites at the very next fetch —
+ * a 401 surfaces as a legible "run `cotal login` again", never a silent hang.
+ *
+ * Device code, not auth-code+PKCE: it works headless (agents, SSH) and needs nothing beyond the
+ * IdP's device endpoints — no OIDC provider metadata, no loopback redirect server (the plan
+ * explicitly avoids Better Auth's draft OIDC-provider surface). Better Auth's
+ * `deviceAuthorization` plugin is the reference IdP; the wire contract this client assumes is
+ * pinned by the login smoke against a real instance. One deliberate deviation from strict
+ * RFC 8628 §3.4: bodies are posted as JSON, because Better Auth's endpoint layer REJECTS
+ * `application/x-www-form-urlencoded` (415). A strict-RFC IdP plugs in via a thin adapter, not
+ * by bending the reference client.
+ *
+ * `idpUrl` throughout is the IdP's AUTH BASE URL — every endpoint resolves under it (Better
+ * Auth: `<origin>/api/auth`). Same origin posture as the JWKS pin: https, or loopback http for
+ * local dev; embedded `user:pass@` credentials are refused (the @-confusion host spoof).
+ *
+ * Every IdP request carries a hard per-request timeout ({@link idpFetch}) — Node's global fetch
+ * has none, and the poll deadline is only checked between polls, so a hung IdP would otherwise
+ * stall a login (or a non-interactive `requireIdpSession`→`fetchIdpJwt` on an agent connect)
+ * forever. Override the 30s default with `COTAL_IDP_TIMEOUT_MS` for a slow IdP.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decodeJwt } from "jose";
+import { mkSecretDir, writeSecretFileAtomic } from "@cotal-ai/core";
+/** Normalize + guard the IdP base URL: https (or loopback http for dev), no query/hash, no
+ *  trailing slash — the normalized string is also the session-cache key, so `…/api/auth` and
+ *  `…/api/auth/` must land on the same entry. */
+export function normalizeIdpUrl(idpUrl) {
+    let u;
+    try {
+        u = new URL(idpUrl);
+    }
+    catch {
+        throw new Error(`idp url "${idpUrl}" is not a valid URL`);
+    }
+    // WHATWG URL keeps the brackets on an IPv6 hostname — "[::1]", not "::1" (same set as the
+    // issuer's pinned-JWKS origin guard).
+    const loopback = u.hostname === "127.0.0.1" || u.hostname === "[::1]" || u.hostname === "localhost";
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && loopback))
+        throw new Error(`idp url must be https (or loopback http for local dev) - got "${idpUrl}"`);
+    // A query/hash would be silently DROPPED by the normalization below — and a silently altered
+    // auth base is a different IdP than the operator asked for. Refuse instead.
+    if (u.search !== "" || u.hash !== "")
+        throw new Error(`idp url must not carry a query or fragment - got "${idpUrl}"`);
+    // Same class: `--idp https://real-idp.example@evil.example/api/auth` parses to host
+    // evil.example, so an operator who eyeballed "real-idp.example" would sign in against evil.
+    // The normalization below drops the userinfo silently — refuse it (don't echo the password).
+    if (u.username !== "" || u.password !== "")
+        throw new Error(`idp url must not embed credentials before the host - the host it would actually contact is "${u.host}"`);
+    return u.origin + u.pathname.replace(/\/+$/, "");
+}
+async function oauthError(res) {
+    try {
+        return (await res.json());
+    }
+    catch {
+        return {};
+    }
+}
+/** Per-request timeout budget (ms). Default 30s; `COTAL_IDP_TIMEOUT_MS` overrides for a slow IdP
+ *  (or a test). A malformed override fails loud rather than silently reverting to the default. */
+function idpTimeoutMs() {
+    const raw = process.env.COTAL_IDP_TIMEOUT_MS;
+    if (raw === undefined)
+        return 30_000;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`COTAL_IDP_TIMEOUT_MS must be a positive number of milliseconds - got "${raw}"`);
+    return n;
+}
+/** `fetch` with a hard per-request timeout, so a hung IdP connection can never stall the client
+ *  (Node's global fetch has no default timeout). A timeout or transport failure surfaces as a
+ *  legible sentence rather than a raw DOMException/TypeError. */
+async function idpFetch(url, init) {
+    const ms = idpTimeoutMs();
+    try {
+        return await fetch(url, { ...init, signal: AbortSignal.timeout(ms) });
+    }
+    catch (e) {
+        if (e instanceof DOMException && e.name === "TimeoutError")
+            throw new Error(`idp request to ${url} timed out after ${ms}ms - the IdP is unreachable or not responding`);
+        throw new Error(`idp request to ${url} failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Read a JSON body under the SAME normalization as {@link idpFetch}. The request timeout can fire
+ *  DURING the body read (an IdP that flushes headers then stalls or truncates the body), and that
+ *  abort is raised from `res.json()` — outside idpFetch's catch — so without this it would leak a
+ *  raw DOMException/parse error instead of the legible "idp request to …" sentence. */
+async function idpJson(url, res) {
+    try {
+        return (await res.json());
+    }
+    catch (e) {
+        if (e instanceof DOMException && e.name === "TimeoutError")
+            throw new Error(`idp request to ${url} timed out reading the response body - the IdP flushed headers then stalled`);
+        throw new Error(`idp request to ${url} returned an unreadable response body: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+/** Best-effort reachability + shape check of an IdP's JWKS. Used at the FIRST `--user-auth` enable
+ *  so a dead or typo'd `--idp` fails loud BEFORE a space is provisioned around it, instead of only
+ *  surfacing far away at the first user connect (the pin is written but the JWKS is fetched lazily).
+ *  Normalizes the URL exactly as the pin does (`<base>/jwks`). Throws a legible sentence on an
+ *  unreachable host, a non-2xx, or a body that is not a JWKS key set. */
+export async function probeIdpJwks(idpUrl) {
+    const jwksUri = `${normalizeIdpUrl(idpUrl)}/jwks`; // a bad scheme throws its own message here
+    const res = await idpFetch(jwksUri);
+    if (!res.ok)
+        throw new Error(`the IdP at ${idpUrl} did not serve a JWKS: ${jwksUri} returned HTTP ${res.status}. Check --idp <auth base URL>.`);
+    const body = await idpJson(jwksUri, res);
+    if (!Array.isArray(body.keys))
+        throw new Error(`the IdP at ${idpUrl} did not return a JWKS key set at ${jwksUri}. Check --idp <auth base URL>; it must expose <base>/jwks.`);
+}
+/** True if `s` parses as a JWT — used to REJECT a JWT where an opaque session token is required.
+ *  The revocation model depends on the cached token being revocable; a JWT stays valid until it
+ *  expires regardless of revocation, so one must never be cached as the session handle. */
+function looksLikeJwt(s) {
+    try {
+        decodeJwt(s);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Sign in via the RFC 8628 device flow and return the IdP session. Fail-loud on every non-happy
+ *  path: a deny, an expiry, or an unknown poll error is a thrown human sentence, never a retry
+ *  loop. Blocks (polling at the server's stated interval) until the human approves. */
+export async function deviceLogin(opts) {
+    const base = normalizeIdpUrl(opts.idpUrl);
+    const res = await idpFetch(`${base}/device/code`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ client_id: opts.clientId }),
+    });
+    if (!res.ok) {
+        const e = await oauthError(res);
+        throw new Error(`idp login: ${base} refused the device authorization (${e.error ?? `HTTP ${res.status}`}: ${e.error_description ?? "no detail"})`);
+    }
+    const grant = await idpJson(`${base}/device/code`, res);
+    // The WHOLE grant is shape-checked before anything is shown or polled — the timing fields
+    // especially: a malicious IdP handing back `interval: "abc"` or a non-finite/absurd
+    // `expires_in` would otherwise turn the poll loop into a tight (setTimeout coerces garbage to
+    // ~1ms) or unbounded one. Bounds: a device code living past 24h or a poll interval past 5min
+    // is not a sane grant — refuse, don't clamp.
+    const sane = (v, max) => typeof v === "number" && Number.isFinite(v) && v > 0 && v <= max;
+    if (typeof grant.device_code !== "string" || !grant.device_code ||
+        typeof grant.user_code !== "string" || !grant.user_code ||
+        typeof grant.verification_uri !== "string" || !grant.verification_uri ||
+        typeof grant.verification_uri_complete !== "string" || !grant.verification_uri_complete ||
+        !sane(grant.expires_in, 86_400) ||
+        (grant.interval !== undefined && !sane(grant.interval, 300)))
+        throw new Error(`idp login: ${base} returned a malformed device grant - refusing to poll on it`);
+    opts.onPrompt({
+        verificationUri: grant.verification_uri,
+        verificationUriComplete: grant.verification_uri_complete,
+        userCode: grant.user_code,
+        expiresInSec: grant.expires_in,
+    });
+    const deadline = Date.now() + grant.expires_in * 1000;
+    // RFC 8628 §3.5: poll at the server's interval; `slow_down` adds 5s to it, permanently.
+    let intervalSec = Math.max(1, grant.interval || 5);
+    for (;;) {
+        await new Promise((r) => setTimeout(r, intervalSec * 1000));
+        if (Date.now() > deadline)
+            throw new Error(`idp login: the device code expired after ${grant.expires_in}s without approval - run \`cotal login\` again`);
+        const poll = await idpFetch(`${base}/device/token`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: grant.device_code,
+                client_id: opts.clientId,
+            }),
+        });
+        if (poll.ok) {
+            const tok = await idpJson(`${base}/device/token`, poll);
+            // Bound the session lifetime like the device grant's timing fields above (finite, positive,
+            // not past a year). `expiresAt` is advisory only — the server is the revocation authority —
+            // so this is a legibility/symmetry guard, not a security boundary: it refuses a hostile
+            // `expires_in: 1e12` rather than caching it and printing "Session cached … until <year 33000>".
+            if (typeof tok.access_token !== "string" || !tok.access_token || !sane(tok.expires_in, 31_536_000))
+                throw new Error(`idp login: ${base} returned a malformed token response`);
+            // Defense-in-depth for the revocation model: we cache the OPAQUE session handle precisely so
+            // that IdP revocation bites at the next /token fetch. A JWT outlives its session, so if a
+            // misconfigured IdP hands one back as the device token, refuse rather than silently cache a
+            // credential that can't be revoked.
+            if (looksLikeJwt(tok.access_token))
+                throw new Error(`idp login: ${base} returned a JWT as the device access token - the session token must be an opaque revocable handle, refusing to cache it; re-run \`cotal login\` after fixing the IdP`);
+            return { token: tok.access_token, expiresAt: Math.floor(Date.now() / 1000) + tok.expires_in };
+        }
+        const e = await oauthError(poll);
+        if (e.error === "authorization_pending")
+            continue;
+        if (e.error === "slow_down") {
+            intervalSec += 5;
+            continue;
+        }
+        if (e.error === "access_denied")
+            throw new Error("idp login: the sign-in was denied at the verification page");
+        if (e.error === "expired_token")
+            throw new Error("idp login: the device code expired before the sign-in was approved - run `cotal login` again");
+        throw new Error(`idp login: ${base} rejected the poll (${e.error ?? `HTTP ${poll.status}`}: ${e.error_description ?? "no detail"})`);
+    }
+}
+/** Fetch a fresh short-lived IdP user JWT for the cached session — the input to the bridge
+ *  exchange. A 401 means the session was revoked or expired at the IdP: the error says exactly
+ *  how to recover. The JWT is returned, never stored. */
+export async function fetchIdpJwt(idpUrl, sessionToken) {
+    const base = normalizeIdpUrl(idpUrl);
+    const res = await idpFetch(`${base}/token`, { headers: { authorization: `Bearer ${sessionToken}` } });
+    if (res.status === 401)
+        throw new Error(`idp session: ${base} rejected the cached session (expired or revoked) - run \`cotal login --idp ${base}\` to sign in again`);
+    if (!res.ok)
+        throw new Error(`idp session: ${base}/token failed (HTTP ${res.status})`);
+    const body = await idpJson(`${base}/token`, res);
+    if (typeof body.token !== "string" || !body.token)
+        throw new Error(`idp session: ${base}/token returned no token`);
+    return body.token;
+}
+/** The whole login operation, in the only safe order: device sign-in, then PROVE the session
+ *  mints a user JWT, and only then persist it. A session that can't produce a JWT must never
+ *  land on disk — it would pass {@link requireIdpSession}'s no-fallback gate as a dud and defer
+ *  the failure to some later connect. Returns the session plus the JWT's `sub`, and a human
+ *  `label` (email/name/preferred_username when the IdP mints one) — BOTH display-only: the
+ *  operator must be able to read WHICH human signed in, but verification is the bridge/callout's
+ *  job, server-side. */
+export async function establishIdpSession(opts) {
+    const session = await deviceLogin(opts);
+    const jwt = await fetchIdpJwt(opts.idpUrl, session.token);
+    let claims;
+    try {
+        claims = decodeJwt(jwt);
+    }
+    catch {
+        // fetchIdpJwt only guarantees a non-empty string; a hostile IdP returning /token 200 with a
+        // non-JWT body would otherwise surface jose's raw "Invalid JWT" here.
+        throw new Error(`idp login: ${normalizeIdpUrl(opts.idpUrl)} returned a /token value that is not a decodable JWT - refusing to cache the session; re-run \`cotal login\` after fixing the IdP`);
+    }
+    const sub = claims.sub;
+    if (typeof sub !== "string" || !sub)
+        throw new Error(`idp login: ${normalizeIdpUrl(opts.idpUrl)} minted a user JWT without a sub - refusing to cache the session; re-run \`cotal login\` after fixing the IdP`);
+    session.sub = sub; // proven above — cached so owner derivation (spawn paths) stays offline
+    saveIdpSession(opts.dir, opts.idpUrl, session);
+    const label = [claims.email, claims.name, claims.preferred_username].find((c) => typeof c === "string" && c.length > 0);
+    return { session, sub, ...(label ? { label } : {}) };
+}
+/** Revoke the session server-side (sign out). A 401 back means the session is already dead —
+ *  the goal state, treated as success; any other failure is thrown because a still-live
+ *  server-side session is a real leak the operator must hear about. */
+export async function revokeIdpSession(idpUrl, sessionToken) {
+    const base = normalizeIdpUrl(idpUrl);
+    const res = await idpFetch(`${base}/sign-out`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${sessionToken}`, "content-type": "application/json" },
+        body: "{}",
+    });
+    if (!res.ok && res.status !== 401)
+        throw new Error(`idp logout: ${base}/sign-out failed (HTTP ${res.status}) - the server-side session may still be alive`);
+}
+// ---- the machine-local session cache ----
+// Explicit-dir APIs like the workspace auth-path helpers: the caller (the `login` command) picks
+// the directory (`homeCotalDir()`); nothing here discovers paths ambiently. One file, all IdPs,
+// keyed by normalized base URL; 0700 dir / 0600 file via core's secret-file helpers.
+const SESSIONS_FILE = "idp-sessions.json";
+const SESSIONS_VER = 1;
+function readSessionsFile(dir) {
+    const f = join(dir, SESSIONS_FILE);
+    if (!existsSync(f))
+        return { ver: SESSIONS_VER, sessions: {} };
+    // A torn write or a hand-edit must not reach requireIdpSession (the no-fallback gate) as a raw
+    // "SyntaxError: Unexpected token" — say what's wrong and how to recover, like everywhere else.
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(f, "utf8"));
+    }
+    catch (e) {
+        throw new Error(`${f}: the session cache is not valid JSON (${e instanceof Error ? e.message : String(e)}) - delete it and run \`cotal login\` again`);
+    }
+    if (parsed === null || typeof parsed !== "object")
+        throw new Error(`${f}: the session cache is not a JSON object - delete it and run \`cotal login\` again`);
+    if (parsed.ver !== SESSIONS_VER)
+        throw new Error(`${f}: unknown version ${String(parsed.ver)} (expected ${SESSIONS_VER}) - refusing to guess at a credential file`);
+    if (parsed.sessions === null || typeof parsed.sessions !== "object" || Array.isArray(parsed.sessions))
+        throw new Error(`${f}: malformed sessions map`);
+    return parsed;
+}
+export function loadIdpSession(dir, idpUrl) {
+    const key = normalizeIdpUrl(idpUrl);
+    const s = readSessionsFile(dir).sessions[key];
+    if (s === undefined)
+        return undefined;
+    if (typeof s.token !== "string" || !s.token || typeof s.expiresAt !== "number")
+        throw new Error(`stored idp session for ${key} is malformed - run \`cotal login --idp ${key}\` again`);
+    // `sub` rides the cache round-trip (offline owner derivation for the spawn paths) — every
+    // consumer of ownerForLogin is a SEPARATE process re-reading this file, so dropping it here
+    // broke both user-mode spawn entry points while every in-process test passed.
+    return { token: s.token, expiresAt: s.expiresAt, ...(typeof s.sub === "string" && s.sub ? { sub: s.sub } : {}) };
+}
+export function saveIdpSession(dir, idpUrl, session) {
+    const file = readSessionsFile(dir);
+    file.sessions[normalizeIdpUrl(idpUrl)] = {
+        token: session.token,
+        expiresAt: session.expiresAt,
+        ...(session.sub ? { sub: session.sub } : {}),
+    };
+    mkSecretDir(dir); // harden the dir BEFORE the secret lands (0700 POSIX, private ACL win32)
+    writeSecretFileAtomic(join(dir, SESSIONS_FILE), JSON.stringify(file, null, 2));
+}
+/** Remove the cached session. Returns false when there was nothing to remove. */
+export function deleteIdpSession(dir, idpUrl) {
+    const key = normalizeIdpUrl(idpUrl);
+    const file = readSessionsFile(dir);
+    if (!(key in file.sessions))
+        return false;
+    delete file.sessions[key];
+    mkSecretDir(dir);
+    writeSecretFileAtomic(join(dir, SESSIONS_FILE), JSON.stringify(file, null, 2));
+    return true;
+}
+/** The no-fallback gate the user-mode connect path consumes: a session or a thrown sentence that
+ *  says exactly how to get one. There is no anonymous degradation when a space requires a user. */
+export function requireIdpSession(dir, idpUrl) {
+    const key = normalizeIdpUrl(idpUrl);
+    const s = loadIdpSession(dir, key);
+    if (!s)
+        throw new Error(`not logged in to ${key} - this space requires a user identity and there is no anonymous fallback; run \`cotal login --idp ${key}\``);
+    return s;
+}
+//# sourceMappingURL=login.js.map

package/dist/login.js.map

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

package/dist/permissions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The callout's `permissionsFor` supplier — the thin `@cotal-ai/auth` adapter that turns a validated
+ * user token into a call to core's IdP-agnostic, principal-shaped `permissionsFor` builder. This is the
+ * boundary the flip's Q4 review pinned: core asserts only the generic owner+actor grammar; this adapter
+ * enforces the token-specific invariants (derived owner, `act.scope` as the single capability authority)
+ * and resolves the agent's channel ACL server-side, then hands core a `MintPrincipal`.
+ */
+import { type MintOpts } from "@cotal-ai/core";
+import type { ValidatedUserToken } from "./token.js";
+/** The per-agent channel/role ACL a user-mode grant needs — resolved SERVER-SIDE (the spawn ledger /
+ *  persona registry, keyed by the authenticated principal), because the user token carries the identity
+ *  and capabilities but NOT the channel read/post ACL. Injected by the composition root that launches the
+ *  callout (`cotal up`), so this package stays free of any ledger/persona storage concern. */
+export type AclResolver = (t: ValidatedUserToken) => Pick<MintOpts, "allowSubscribe" | "allowPublish" | "role">;
+/**
+ * Build the callout's `permissionsFor` hook. Maps `ValidatedUserToken` → `MintPrincipal` → core's
+ * `permissionsFor("agent", …)`. `connId` here is the CLIENT-CHOSEN inbox nonce the callout reads from
+ * `req.connect_opts.name` (NOT `req.user_nkey`, which the client cannot know pre-connect); it scopes the
+ * reply inbox `_INBOX_<connId>.>`.
+ *
+ * Invariants enforced HERE (not in core):
+ *  - the owner is a DERIVED owner (`u_…`) — user mode never accepts the reserved dev `local` owner;
+ *  - `act.scope` is the SINGLE capability authority: a token that ALSO carries a top-level `scope` must
+ *    have them agree, else it is rejected (the confused-authority guard the Q4 review required closed the
+ *    moment `permissionsFor(validated)` became production).
+ */
+export declare function calloutPermissions(resolveAcl: AclResolver): (t: ValidatedUserToken, connId: string) => Record<string, unknown>;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAmF,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAEhI,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;;8FAG8F;AAC9F,MAAM,MAAM,WAAW,GAAG,CACxB,CAAC,EAAE,kBAAkB,KAClB,IAAI,CAAC,QAAQ,EAAE,gBAAgB,GAAG,cAAc,GAAG,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,WAAW,GACtB,CAAC,CAAC,EAAE,kBAAkB,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiCpE"}

package/dist/permissions.js

@@ -0,0 +1,50 @@
+/**
+ * The callout's `permissionsFor` supplier — the thin `@cotal-ai/auth` adapter that turns a validated
+ * user token into a call to core's IdP-agnostic, principal-shaped `permissionsFor` builder. This is the
+ * boundary the flip's Q4 review pinned: core asserts only the generic owner+actor grammar; this adapter
+ * enforces the token-specific invariants (derived owner, `act.scope` as the single capability authority)
+ * and resolves the agent's channel ACL server-side, then hands core a `MintPrincipal`.
+ */
+import { permissionsFor, assertDerivedOwnerToken, CONTROL_PRIVILEGED } from "@cotal-ai/core";
+import { VIEW_REQUIRED_SCOPE } from "./token.js";
+/**
+ * Build the callout's `permissionsFor` hook. Maps `ValidatedUserToken` → `MintPrincipal` → core's
+ * `permissionsFor("agent", …)`. `connId` here is the CLIENT-CHOSEN inbox nonce the callout reads from
+ * `req.connect_opts.name` (NOT `req.user_nkey`, which the client cannot know pre-connect); it scopes the
+ * reply inbox `_INBOX_<connId>.>`.
+ *
+ * Invariants enforced HERE (not in core):
+ *  - the owner is a DERIVED owner (`u_…`) — user mode never accepts the reserved dev `local` owner;
+ *  - `act.scope` is the SINGLE capability authority: a token that ALSO carries a top-level `scope` must
+ *    have them agree, else it is rejected (the confused-authority guard the Q4 review required closed the
+ *    moment `permissionsFor(validated)` became production).
+ */
+export function calloutPermissions(resolveAcl) {
+    return (t, connId) => {
+        assertDerivedOwnerToken(t.owner); // user-mode owners are derived — never `local`, never an nkey
+        const caps = t.act.scope ?? [];
+        // Single capability authority: if a top-level `scope` is present it must equal `act.scope` exactly —
+        // two independent capability lists is a confused-authority footgun (which one gates the spawn grant?).
+        const norm = (xs) => JSON.stringify([...xs].sort());
+        if (t.scope.length && norm(t.scope) !== norm(caps))
+            throw new Error("callout permissions: top-level scope != act.scope - act.scope is the single capability authority");
+        const principal = { owner: t.owner, actor: t.act.actor, connId };
+        if (t.act.view !== undefined) {
+            // ELEVATED VIEW: the exchange already ledger-authorized it, and `ledgerAuthorizeConnect`
+            // fresh-read the row again this connect (act.scope ⊆ current row enforced there) — here is
+            // the LAST defense-in-depth re-assert: the bearer's own capability list must carry the
+            // view's required scope, or nothing is minted. View names ARE profile names (a closed enum,
+            // never a client-chosen profile passthrough); channel ACLs don't apply to these profiles.
+            const need = VIEW_REQUIRED_SCOPE[t.act.view];
+            if (!caps.includes(need))
+                throw new Error(`callout permissions: view "${t.act.view}" without capability "${need}" in act.scope - refusing to mint`);
+            return permissionsFor(t.act.view, t.space, principal, 
+            // The user-mode deployer's control calls ride the PRIVILEGED tier: the manager's
+            // owner-equality launch authorization governs, never the admin-tier bypass.
+            t.act.view === "deployer" ? { controlTier: CONTROL_PRIVILEGED } : {});
+        }
+        const acl = resolveAcl(t);
+        return permissionsFor("agent", t.space, principal, { ...acl, capabilities: caps });
+    };
+}
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,kBAAkB,EAAqC,MAAM,gBAAgB,CAAC;AAChI,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAWjD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAuB;IAEvB,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;QACnB,uBAAuB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,8DAA8D;QAChG,MAAM,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/B,qGAAqG;QACrG,uGAAuG;QACvG,MAAM,IAAI,GAAG,CAAC,EAAY,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9D,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC;YAChD,MAAM,IAAI,KAAK,CACb,kGAAkG,CACnG,CAAC;QACJ,MAAM,SAAS,GAAkB,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QAChF,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,yFAAyF;YACzF,2FAA2F;YAC3F,uFAAuF;YACvF,4FAA4F;YAC5F,0FAA0F;YAC1F,MAAM,IAAI,GAAG,mBAAmB,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;gBACtB,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,GAAG,CAAC,IAAI,yBAAyB,IAAI,mCAAmC,CAAC,CAAC;YAC5H,OAAO,cAAc,CACnB,CAAC,CAAC,GAAG,CAAC,IAAI,EACV,CAAC,CAAC,KAAK,EACP,SAAS;YACT,iFAAiF;YACjF,4EAA4E;YAC5E,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CACrE,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,OAAO,cAAc,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,GAAG,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;IACrF,CAAC,CAAC;AACJ,CAAC"}

package/dist/provider.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The core `auth-provider` extension — how a composition root gets user-mode auth WITHOUT importing
+ * this package from the CLI (`bin/cotal.ts` imports `@cotal-ai/auth`; `@cotal-ai/cli` resolves the
+ * provider from the registry, generically).
+ *
+ * `prepareServer` is the `cotal up --user-auth` hook. It receives the NARROW provisioning input
+ * (core's {@link AuthPrepareInput}: operator seed + data-account pub/signingSeed + the space-scoped
+ * state dir — never the whole space bundle), makes all persisted material exist, projects the ONE
+ * signing seed the daemon may hold into `service-keys.json`, and hands back:
+ *  - the callout account for the broker config preload,
+ *  - the non-secret client metadata (trust pins) the workstation registry records ({@link
+ *    assertUserAuthInfo} shape — typed in workspace, opaque to core),
+ *  - the service handle: the `auth-service` command name + the readiness contract (poll the
+ *    discovery file the daemon writes only after BOTH planes are bound, then confirm /health).
+ */
+import { type AuthProvider } from "@cotal-ai/core";
+export declare const cotalAuthProvider: AuthProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAsD,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AA4BvG,eAAO,MAAM,iBAAiB,EAAE,YA8L/B,CAAC"}