@anchrd/intel-api 0.3.2 → 0.4.0

package/README.md

@@ -72,8 +72,18 @@ uses PKCE and dynamic public-client registration; browser access tokens stay ins
 `node_modules/@anchrd/intel-api/examples/dev.vars.example` to `.dev.vars` for a local customer Worker.
 
 The portal endpoint exposes RFC 9728 metadata. The Tools UI follows that metadata, dynamically
-registers with Gate or Cloudflare Access, and completes a separate PKCE flow. The only tool secret
-Intel stores is the resulting per-user access token for its own portal endpoint, sealed with a key
+registers with Gate or Cloudflare Access, and completes a separate PKCE flow — silently, with
+`prompt=none`, as soon as a Gate session exists. Nobody is asked to connect anything.
+
+⚠️ **Two settings outside this repository decide whether that silent sign-in can work.** In
+Cloudflare Zero Trust → Access controls → AI controls → your portal → Edit → Advanced settings,
+`Managed OAuth` must be enabled, and an Access policy must carry the people who use Intel. Without
+both, every silent sign-in is refused and the Tools area shows "No access to the company portal" —
+correct behaviour for somebody outside every policy, and a misleading one for a deployment that
+simply never enabled the setting.
+
+The only tool secret Intel stores is the resulting per-user access token for its own portal
+endpoint — one per person, never one shared operator token — sealed with a key
 derived from `INTEL_SESSION_SECRET` and kept in the `portal_tokens` table of your D1; provider
 credentials stay with the portal and never reach Intel. The Intel audience token is never forwarded
 to another OAuth resource.

package/dist/adapters/openid/openid.js

@@ -141,6 +141,7 @@ export function createOpenId(deps) {
                 code_challenge: input.codeChallenge,
                 code_challenge_method: "S256",
                 state: input.state,
+                ...(input.prompt ? { prompt: input.prompt } : {}),
             });
         },
         async exchange(input) {

package/dist/adapters/session-cookie/session-cookie.js

@@ -27,6 +27,9 @@ const ConnectionPendingSession = z.strictObject({
     resource: z.url(),
     userId: z.string().min(1),
     user: UserSession,
+    // Older cookies carry no `silent`, and one in flight across a deploy must not become an invalid
+    // session: absent means the visible flow, which is what those attempts were.
+    silent: z.boolean().default(false),
     expiresAt: z.number().int().positive(),
 });
 const Session = z.discriminatedUnion("kind", [

package/dist/auth/auth.js

@@ -2,6 +2,22 @@ import { calculatePKCECodeChallenge, randomPKCECodeVerifier, randomState } from
 import { IntelError } from "../shared/intel-error/intel-error.js";
 import { SafeReturnPath } from "../shared/safe-return-path/safe-return-path.js";
 const cookieName = "intel_session";
+// What an authorization server answers when `prompt=none` would have worked, but only with somebody
+// looking at a screen. It is the expected answer to a silent attempt, not a broken deployment.
+const InteractionRequired = new Set([
+    "login_required",
+    "interaction_required",
+    "consent_required",
+    "account_selection_required",
+]);
+// One fixed marker, never the portal's own words. `error_description` is a sentence written by the
+// authorization server about somebody else's policy: putting it in the URL would hand whatever
+// renders the page next a string Intel does not control.
+function withConnectError(returnTo) {
+    const url = new URL(returnTo, "https://intel.invalid");
+    url.searchParams.set("connectError", "portal_sign_in_refused");
+    return `${url.pathname}${url.search}`;
+}
 function cookieValue(headers) {
     const values = headers.get("cookie")?.split(";") ?? [];
     for (const value of values) {
@@ -51,6 +67,15 @@ export function createBrowserAuth(deps) {
             createdAt: deps.now().toISOString(),
         });
     }
+    // The connection handoff parks the Intel session inside the pending cookie, so every way out of
+    // the callback has to put it back — the portal attempt must never cost somebody their Intel login.
+    async function restore(user, returnTo, location) {
+        const remaining = (user.expiresAt - deps.now().getTime()) / 1_000;
+        if (remaining <= 0) {
+            return redirect(`/auth/login?returnTo=${encodeURIComponent(returnTo)}`, sessionCookie("", secure, 0));
+        }
+        return redirect(location, sessionCookie(await deps.sessions.seal(user), secure, remaining));
+    }
     async function userSession(client, tokens) {
         return {
             version: 1,
@@ -93,6 +118,10 @@ export function createBrowserAuth(deps) {
                 throw new IntelError(401, "authentication_required", "Authentication is required");
             }
             const returnTo = SafeReturnPath.catch("/tools").parse(requestUrl.searchParams.get("returnTo") ?? "/tools");
+            // Gate is the OIDC provider Cloudflare Access consumes, so whoever holds a valid Intel
+            // session is already the person the portal would ask about. `prompt=none` says exactly that:
+            // answer from the session that exists, and refuse rather than show anybody a login (#60).
+            const silent = requestUrl.searchParams.get("silent") === "1";
             if (!deps.portalUrl) {
                 throw new IntelError(503, "portal_not_configured", "No MCP portal is configured for this deployment");
             }
@@ -113,6 +142,7 @@ export function createBrowserAuth(deps) {
                 resource: discovered.resource,
                 userId,
                 user,
+                silent,
                 expiresAt: deps.now().getTime() + 10 * 60 * 1_000,
             };
             const authorizationUrl = await deps.oauth.authorizationUrl({
@@ -123,6 +153,7 @@ export function createBrowserAuth(deps) {
                 codeChallenge,
                 state,
                 ...(discovered.scope ? { scope: discovered.scope } : {}),
+                ...(silent ? { prompt: "none" } : {}),
             });
             return redirect(authorizationUrl.href, sessionCookie(await deps.sessions.seal(pending), secure, 10 * 60));
         },
@@ -133,6 +164,19 @@ export function createBrowserAuth(deps) {
                 pending.expiresAt <= deps.now().getTime()) {
                 throw new IntelError(400, "oauth_session_invalid", "OAuth session is missing or expired");
             }
+            // ⚠️ An authorization server reports a refusal on the redirect URI, not by failing the token
+            // exchange. Reading it here is what keeps a refused silent attempt from surfacing as a raw
+            // OAuth error, and it is the only place that knows whether a visible attempt is still owed.
+            const refusal = requestUrl.searchParams.get("error");
+            if (pending.kind === "connection-pending" && refusal) {
+                // The silent attempt only asked whether the sign-in works without a screen. "Not without
+                // one" is an answer, so the visible flow runs once — and because that one is not silent, a
+                // second refusal ends in the message instead of a third attempt.
+                const visibleAttemptLeft = pending.silent && InteractionRequired.has(refusal);
+                return await restore(pending.user, pending.returnTo, visibleAttemptLeft
+                    ? `/auth/connect?returnTo=${encodeURIComponent(pending.returnTo)}`
+                    : withConnectError(pending.returnTo));
+            }
             const tokens = await deps.oauth.exchange({
                 issuer: pending.kind === "connection-pending" ? pending.issuer : gateIssuer,
                 clientId: pending.clientId,
@@ -151,11 +195,7 @@ export function createBrowserAuth(deps) {
                     clientId: pending.clientId,
                     resource: pending.resource,
                 });
-                const remaining = (pending.user.expiresAt - deps.now().getTime()) / 1_000;
-                if (remaining <= 0) {
-                    return redirect(`/auth/login?returnTo=${encodeURIComponent(pending.returnTo)}`, sessionCookie("", secure, 0));
-                }
-                return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(pending.user), secure, remaining));
+                return await restore(pending.user, pending.returnTo, pending.returnTo);
             }
             const session = await userSession(pending.clientId, tokens);
             return redirect(pending.returnTo, sessionCookie(await deps.sessions.seal(session), secure, (session.expiresAt - deps.now().getTime()) / 1_000));

package/dist/auth/auth.types.d.ts

@@ -24,6 +24,7 @@ export interface OAuthPort {
         codeChallenge: string;
         state: string;
         scope?: string;
+        prompt?: "none";
     }): Promise<URL>;
     exchange(input: {
         issuer: string;
@@ -76,6 +77,7 @@ export type AuthSession = {
     resource: string;
     userId: string;
     user: UserAuthSession;
+    silent: boolean;
     expiresAt: number;
 } | UserAuthSession;
 export interface SessionCodec {

package/dist/intel/intel.js

@@ -32,7 +32,9 @@ export function createIntel(deps) {
     const browserAuth = deps.auth;
     if (browserAuth) {
         app.get("/auth/login", async (context) => await browserAuth.login(new URL(context.req.url)));
-        // One connect route for the one portal: there are no per-source connections any more.
+        // One connect route for the one portal: there are no per-source connections any more. With
+        // `?silent=1` it runs `prompt=none`, which is how the Tools screen reaches it without anybody
+        // clicking (#60); the route itself is unchanged otherwise, including who may use it.
         app.get("/auth/connect", async (context) => {
             const connectReturnTo = encodeURIComponent("/auth/connect?returnTo=/tools");
             const session = await browserAuth.resolve(context.req.raw.headers);

package/dist/tools/tools.js

@@ -12,20 +12,23 @@ export function createTools(deps) {
         return deps.portalUrl;
     }
     // Authorization for tools lives entirely in the portal, so "may this user act" reduces to "does
-    // this user have a usable portal token".
+    // this user have a usable portal token". ⚠️ The token is read per actor and never shared: one
+    // operator token for everybody would make every catalog the same one and the portal's Access
+    // policies decorative (ADR-0003).
     async function accessToken(actor) {
         const stored = await deps.tokens.read(actor.id);
         if (!stored) {
-            throw new IntelError(401, "portal_not_connected", "Connect the MCP portal to use tools");
+            throw new IntelError(401, "portal_not_connected", "The portal has not signed this user in yet");
         }
         if (stored.expiresAt > deps.now().getTime() + RefreshWindowMs)
             return stored.accessToken;
         const refreshed = stored.refreshToken ? await deps.refresh(stored) : null;
         if (!refreshed) {
             // A token that cannot be renewed is dropped: leaving it would keep failing every call with a
-            // stale credential instead of prompting a reconnect.
+            // stale credential. The browser answers this by signing in silently again (#60); an MCP
+            // client sees the code and repeats its own authorization.
             await deps.tokens.clear(actor.id);
-            throw new IntelError(401, "portal_reconnect_required", "Reconnect the MCP portal to continue");
+            throw new IntelError(401, "portal_reconnect_required", "The portal sign-in for this user has expired");
         }
         await deps.tokens.write(actor.id, refreshed);
         return refreshed.accessToken;
@@ -83,17 +86,18 @@ export function createTools(deps) {
     return {
         async catalog(actor) {
             const stored = await deps.tokens.read(actor.id);
-            // An unconnected portal is a normal state, not an error: the UI shows a connect prompt.
+            // No portal sign-in yet is a normal state, not an error: the browser answers it by running
+            // the silent sign-in and asking again (#60).
             if (!stored)
                 return { portalConnected: false, items: [] };
             try {
                 return { portalConnected: true, items: await capabilities(actor) };
             }
             catch (error) {
-                // A token that is gone or beyond renewal is the same answer as never having connected, so
+                // A token that is gone or beyond renewal is the same answer as never having signed in, so
                 // reading the catalog reports it as a state. Only a portal that does not answer stays an
-                // error — the view has to tell "connect the portal" apart from "the portal failed", and a
-                // 401 here would otherwise look like an expired Intel session to the browser.
+                // error — the view has to tell "sign in again" apart from "the portal failed", and a 401
+                // here would otherwise look like an expired Intel session to the browser.
                 if (error instanceof IntelError &&
                     (error.code === "portal_not_connected" || error.code === "portal_reconnect_required")) {
                     return { portalConnected: false, items: [] };

package/migrations/0005_tables_in_the_knowledge_tree.sql

@@ -2,15 +2,39 @@
 -- `parent_id`, same folder grants, same immutable `knowledge_versions` rows, same R2 body
 -- (ADR-0004 §1). Nothing here creates a second content model; only the CHECK has to learn the word.
 --
--- SQLite cannot alter a CHECK constraint, so the table is rebuilt. Dropping the old table would
--- otherwise trip the foreign keys of `knowledge_versions`, `knowledge_links`, `tree_grants` and
--- `flows`; deferring them to the end of the migration lets the rename put the same IDs back under
--- the same name before anything is checked.
+-- SQLite cannot alter a CHECK constraint, so the table is rebuilt. The rebuild is written the long
+-- way round, and both detours are here because the short way was tried and D1 rolled it back. The
+-- table this migration leaves behind is the same one either way — same columns, same constraints,
+-- same indexes — so an installation that already applied this file keeps exactly what it has.
+--
+-- ⚠️ First detour: the new table is created under the final name rather than built beside the old
+-- one and renamed over it. `DROP TABLE` on a parent runs an implicit `DELETE FROM` first, so the
+-- moment the old `knowledge_nodes` goes, every row of `knowledge_versions`, `tree_grants` and
+-- `flows` pointing at a node is a foreign-key violation. `defer_foreign_keys` postpones the
+-- complaint to COMMIT but does not withdraw it, and `ALTER TABLE ... RENAME` does not settle it
+-- either: a rename puts the name back, not the rows. Only inserting the nodes again, under the name
+-- the children have referenced all along, does. On an empty database none of this is visible —
+-- nothing points at anything — which is precisely how the first version passed a green test suite
+-- and then failed against the first database that had content in it.
+--
+-- ⚠️ Second detour: `knowledge_links` is the only child of `knowledge_nodes` declared ON DELETE
+-- CASCADE, so that same implicit delete does not merely flag its rows, it removes them — the
+-- migration would have committed with every relationship between two documents quietly gone. The
+-- rows are carried out of the way first and put back afterwards. That is a rescue, not a decision
+-- about the data: nothing is dropped, rewritten or reinterpreted here.
 PRAGMA defer_foreign_keys = TRUE;
 
-CREATE TABLE knowledge_nodes_next (
+-- Plain holding tables on purpose: no keys, no CHECKs, no foreign keys, and the column set taken
+-- from whatever the live table has. Anything enforced here would only be enforced a second time on
+-- the way back in, and a holding table that can reject a row is a holding table that can lose one.
+CREATE TABLE knowledge_nodes_carry AS SELECT * FROM knowledge_nodes;
+CREATE TABLE knowledge_links_carry AS SELECT * FROM knowledge_links;
+
+DROP TABLE knowledge_nodes;
+
+CREATE TABLE knowledge_nodes (
   id TEXT PRIMARY KEY NOT NULL,
-  parent_id TEXT REFERENCES knowledge_nodes_next(id),
+  parent_id TEXT REFERENCES knowledge_nodes(id),
   kind TEXT NOT NULL CHECK (kind IN ('folder', 'document', 'attachment', 'table')),
   title TEXT NOT NULL CHECK (length(title) BETWEEN 1 AND 240),
   description TEXT CHECK (description IS NULL OR length(description) <= 2000),
@@ -22,18 +46,23 @@ CREATE TABLE knowledge_nodes_next (
   archived_at TEXT
 );
 
-INSERT INTO knowledge_nodes_next (
+INSERT INTO knowledge_nodes (
   id, parent_id, kind, title, description, context_policy, owner_id,
   current_version_id, created_at, updated_at, archived_at
 )
 SELECT
   id, parent_id, kind, title, description, context_policy, owner_id,
   current_version_id, created_at, updated_at, archived_at
-FROM knowledge_nodes;
+FROM knowledge_nodes_carry;
 
-DROP TABLE knowledge_nodes;
+-- `OR IGNORE` because whether the cascade above actually fired is SQLite's business, not this
+-- migration's: if it did, this puts the rows back; if it did not, each one is already present under
+-- the same primary key and this is a no-op. Either way `knowledge_links` ends up holding exactly
+-- what it held before, which is the only outcome this statement is permitted to have.
+INSERT OR IGNORE INTO knowledge_links SELECT * FROM knowledge_links_carry;
 
-ALTER TABLE knowledge_nodes_next RENAME TO knowledge_nodes;
+DROP TABLE knowledge_nodes_carry;
+DROP TABLE knowledge_links_carry;
 
 CREATE INDEX knowledge_nodes_parent_idx ON knowledge_nodes(parent_id, archived_at, title);
 CREATE INDEX knowledge_nodes_owner_idx ON knowledge_nodes(owner_id, archived_at);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {