@tpsdev-ai/flair 0.11.0 → 0.13.0

package/dist/resources/SemanticSearch.js

@@ -1,42 +1,13 @@
 import { Resource, databases } from "@harperfast/harper";
+import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
 import { getEmbedding, getMode } from "./embeddings-provider.js";
 import { patchRecord, withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
 import { wrapUntrusted } from "./content-safety.js";
-// ─── Temporal Decay + Relevance Scoring ─────────────────────────────────────
-const DURABILITY_WEIGHTS = {
-    permanent: 1.0,
-    persistent: 0.9,
-    standard: 0.7,
-    ephemeral: 0.4,
-};
-// Half-life in days for exponential decay per durability level
-const DECAY_HALF_LIFE_DAYS = {
-    permanent: Infinity, // never decays
-    persistent: 90,
-    standard: 30,
-    ephemeral: 7,
-};
-function recencyFactor(createdAt, durability) {
-    const halfLife = DECAY_HALF_LIFE_DAYS[durability] ?? 30;
-    if (halfLife === Infinity)
-        return 1.0;
-    const ageDays = (Date.now() - Date.parse(createdAt)) / (1000 * 60 * 60 * 24);
-    const lambda = Math.LN2 / halfLife;
-    return Math.exp(-lambda * ageDays);
-}
-function retrievalBoost(retrievalCount) {
-    if (!retrievalCount || retrievalCount <= 0)
-        return 1.0;
-    return 1.0 + 0.1 * Math.log2(retrievalCount); // gentle boost: 10 retrievals → ~1.33x
-}
-function compositeScore(semanticScore, record) {
-    const durability = record.durability ?? "standard";
-    const dWeight = DURABILITY_WEIGHTS[durability] ?? 0.7;
-    const rFactor = record.createdAt ? recencyFactor(record.createdAt, durability) : 1.0;
-    const rBoost = retrievalBoost(record.retrievalCount ?? 0);
-    return semanticScore * dWeight * rFactor * rBoost;
-}
+// Temporal decay + relevance scoring (incl. the OPS-AYGD retrievalBoost cap +
+// relevance floor) lives in ./scoring.ts — a Harper-free module so it can be
+// unit-tested directly (see test/unit/temporal-scoring.test.ts).
+import { compositeScore } from "./scoring.js";
 // Convert HNSW cosine distance (1 - similarity) to similarity score
 function distanceToSimilarity(distance) {
     return 1 - distance;
@@ -45,6 +16,15 @@ function distanceToSimilarity(distance) {
 // so composite re-ranking has enough headroom to reorder results.
 const CANDIDATE_MULTIPLIER = 5;
 export class SemanticSearch extends Resource {
+    // Self-authorize via the Ed25519 agent verify instead of relying on the auth
+    // gate's admin super_user elevation (removed in the auth reshape). Any
+    // cryptographically-verified agent may search; per-agent RESULT scoping is
+    // enforced in post() below (an agent only sees its own + office-visible +
+    // granted memories). Without this, Harper's default denies the POST for the
+    // least-privilege flair_agent role (AccessViolation 403).
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
     async post(data) {
         const { agentId: bodyAgentId, q, queryEmbedding, tag, subject, subjects, limit = 10, includeSuperseded = false, scoring = "composite", minScore = 0, since, asOf } = data || {};
         // Authenticated identity lives on the Harper Resource context (getContext().request).
@@ -52,11 +32,18 @@ export class SemanticSearch extends Resource {
         // silently returned undefined and the defense-in-depth scope check below
         // was bypassed, letting a non-admin agent read another agent's memories
         // by putting the victim's id in the body.
-        const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        const authenticatedAgent = request?.tpsAgent ?? request?.headers?.get?.("x-tps-agent");
-        const callerIsAdmin = request?.tpsAgentIsAdmin === true;
-        // Rate limiting — use authenticated agent ID, not client-supplied body
+        const auth = await resolveAgentAuth(this.getContext?.());
+        // Anonymous HTTP must NOT search. Previously the no-auth path fell through to
+        // honoring the body-supplied agentId (line below), so an unauthenticated
+        // caller could read any agent's memories by putting that id in the body.
+        if (auth.kind === "anonymous") {
+            return new Response(JSON.stringify({ error: "authentication required" }), {
+                status: 401, headers: { "Content-Type": "application/json" },
+            });
+        }
+        const authenticatedAgent = auth.kind === "agent" ? auth.agentId : undefined;
+        const callerIsAdmin = auth.kind === "agent" && auth.isAdmin;
+        // Rate limiting — use authenticated agent ID (internal calls have none).
         if (authenticatedAgent) {
             const bucket = q && !queryEmbedding ? "embedding" : "general";
             const rl = checkRateLimit(authenticatedAgent, bucket);
@@ -70,14 +57,14 @@ export class SemanticSearch extends Resource {
                 : null;
         // Enforce agentId = authenticated agent for non-admins. A mismatched body
         // agentId is a cross-agent read attempt — reject outright. Admins can query
-        // any agentId (needed for bootstrap / consolidation scripts).
+        // any agentId (bootstrap / consolidation).
         if (authenticatedAgent && !callerIsAdmin && bodyAgentId && bodyAgentId !== authenticatedAgent) {
             return new Response(JSON.stringify({
                 error: "forbidden: agentId must match authenticated agent",
             }), { status: 403, headers: { "Content-Type": "application/json" } });
         }
-        // Scope search to the authenticated agent (own + granted). For admins or
-        // unauthenticated internal calls, honor the body-supplied agentId.
+        // Scope: non-admin agent → own (+ granted). Admin agent or trusted internal
+        // call (no request) → honor the body-supplied agentId.
         const agentId = (authenticatedAgent && !callerIsAdmin)
             ? authenticatedAgent
             : bodyAgentId;

package/dist/resources/Soul.js

@@ -1,17 +1,26 @@
 import { databases } from "@harperfast/harper";
-function enforceAgentScope(self, data) {
-    const authenticatedAgent = self.request?.headers?.get?.("x-tps-agent");
-    const callerIsAdmin = self.request?.tpsAgentIsAdmin === true;
-    if (authenticatedAgent && !callerIsAdmin && data?.agentId && data.agentId !== authenticatedAgent) {
-        return new Response(JSON.stringify({
-            error: "forbidden: agentId must match authenticated agent",
-        }), { status: 403, headers: { "Content-Type": "application/json" } });
+import { resolveAgentAuth } from "./agent-auth.js";
+const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
+/**
+ * Deny anonymous; enforce per-agent write ownership for non-admin agents.
+ * The previous header-based check only fired when an agent WAS present (it read
+ * x-tps-agent), so an anonymous request — which carries no x-tps-agent — slipped
+ * through. With the non-rejecting gate, each write path self-enforces (resolveAgentAuth
+ * distinguishes internal/agent/anonymous). Mirrors the WorkspaceState pattern.
+ */
+async function enforceWriteAuth(self, data) {
+    const auth = await resolveAgentAuth(self.getContext?.());
+    if (auth.kind === "anonymous")
+        return UNAUTH();
+    if (auth.kind === "agent" && !auth.isAdmin && data?.agentId && data.agentId !== auth.agentId) {
+        return FORBIDDEN("forbidden: agentId must match authenticated agent");
     }
     return null;
 }
 export class Soul extends databases.flair.Soul {
     async post(content, context) {
-        const denied = enforceAgentScope(this, content);
+        const denied = await enforceWriteAuth(this, content);
         if (denied)
             return denied;
         content.durability ||= "permanent";
@@ -20,7 +29,7 @@ export class Soul extends databases.flair.Soul {
         return super.post(content, context);
     }
     async put(content, context) {
-        const denied = enforceAgentScope(this, content);
+        const denied = await enforceWriteAuth(this, content);
         if (denied)
             return denied;
         content.updatedAt = new Date().toISOString();

package/dist/resources/SoulFeed.js

@@ -1,5 +1,12 @@
 import { Resource, databases } from '@harperfast/harper';
+import { allowVerified } from './agent-auth.js';
 export class FeedSouls extends Resource {
+    // Self-authorize the subscription via the Ed25519 agent verify (auth reshape
+    // removes the gate's admin elevation). FeedSouls extends Resource (not a Table),
+    // so getContext().request is reachable in allow* — same pattern as SemanticSearch.
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
     async *connect(target, incomingMessages) {
         const subscription = await databases.flair.Soul.subscribe(target);
         if (!incomingMessages) {

package/dist/resources/WorkspaceLatest.js

@@ -5,7 +5,14 @@
  * Auth: requesting agent must match agentId in path (or be admin).
  */
 import { Resource, databases } from "@harperfast/harper";
+import { allowVerified } from "./agent-auth.js";
 export class WorkspaceLatest extends Resource {
+    // Self-authorize via the Ed25519 agent verify (auth reshape removes the gate's
+    // admin elevation). Any verified agent may read; the path-vs-agent ownership
+    // check stays in get().
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
     async get(pathInfo) {
         const request = this.context?.request ?? this.request;
         const callerAgent = request?.tpsAgent;

package/dist/resources/WorkspaceState.js

@@ -8,30 +8,30 @@
  * Use this.getContext() to access request context (tpsAgent, tpsAgentIsAdmin).
  */
 import { databases } from "@harperfast/harper";
+import { resolveAgentAuth } from "./agent-auth.js";
+const FORBIDDEN = (msg) => new Response(JSON.stringify({ error: msg }), { status: 403, headers: { "Content-Type": "application/json" } });
+const UNAUTH = () => new Response(JSON.stringify({ error: "authentication required" }), { status: 401, headers: { "Content-Type": "application/json" } });
 export class WorkspaceState extends databases.flair.WorkspaceState {
-    /**
-     * Helper to extract auth info from Harper's Resource instance context.
-     */
-    _authInfo() {
-        const ctx = this.getContext?.();
-        const request = ctx?.request ?? ctx;
-        return {
-            agentId: request?.tpsAgent,
-            isAdmin: request?.tpsAgentIsAdmin ?? false,
-        };
+    /** Auth verdict from the request context. internal = trusted in-process call;
+     *  agent = verified Ed25519; anonymous = HTTP with no valid agent → deny. */
+    _auth() {
+        return resolveAgentAuth(this.getContext?.());
     }
     /**
-     * Override search() to scope collection GETs to the authenticated agent's
-     * own workspace state records. Admin agents see all records.
+     * Override search() to scope collection GETs to the authenticated agent's own
+     * records. Internal calls + admin agents see all; anonymous is denied
+     * (previously `!authAgent` was treated as unfiltered — the anonymous-read leak).
      */
     async search(query) {
-        const { agentId: authAgent, isAdmin: isAdminAgent } = this._authInfo();
-        if (!authAgent || isAdminAgent) {
+        const auth = await this._auth();
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.search(query);
         }
-        const agentIdCondition = { attribute: "agentId", comparator: "equals", value: authAgent };
-        // Harper passes `query` as a request target object (with pathname, id, isCollection, etc.)
-        // Inject scope condition into its `.conditions` array so Table.search() processes it correctly.
+        const agentIdCondition = { attribute: "agentId", comparator: "equals", value: auth.agentId };
+        // Harper passes `query` as a request target object (pathname, id, isCollection…).
+        // Inject the scope condition into its `.conditions` array.
         if (query && typeof query === "object" && !Array.isArray(query)) {
             const existing = query.conditions ?? [];
             query.conditions = Array.isArray(existing)
@@ -45,31 +45,41 @@ export class WorkspaceState extends databases.flair.WorkspaceState {
         return super.search(conditions);
     }
     async post(content) {
-        const { agentId, isAdmin: isAdminAgent } = this._authInfo();
-        // Agent-scoped: agentId in body must match authenticated agent
-        if (agentId && !isAdminAgent && content.agentId !== agentId) {
-            return new Response(JSON.stringify({ error: "forbidden: cannot write workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        const auth = await this._auth();
+        // Anonymous must NOT write (previously the agentId check was skipped when
+        // there was no authenticated agent, so anonymous could write any record).
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
+            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
         }
         content.createdAt = new Date().toISOString();
         content.timestamp ||= content.createdAt;
         return super.post(content);
     }
     async put(content) {
-        const { agentId, isAdmin: isAdminAgent } = this._authInfo();
-        if (agentId && !isAdminAgent && content.agentId !== agentId) {
-            return new Response(JSON.stringify({ error: "forbidden: cannot write workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        const auth = await this._auth();
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "agent" && !auth.isAdmin && content.agentId !== auth.agentId) {
+            return FORBIDDEN("forbidden: cannot write workspace state for another agent");
         }
         return super.put(content);
     }
     async delete(id) {
-        const { agentId, isAdmin: isAdminAgent } = this._authInfo();
-        if (!agentId)
+        const auth = await this._auth();
+        // Anonymous must NOT delete (previously `!agentId → super.delete` let anonymous
+        // delete any record).
+        if (auth.kind === "anonymous")
+            return UNAUTH();
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return super.delete(id);
+        }
         const record = await this.get(id);
         if (!record)
             return super.delete(id);
-        if (!isAdminAgent && record.agentId !== agentId) {
-            return new Response(JSON.stringify({ error: "forbidden: cannot delete workspace state for another agent" }), { status: 403, headers: { "Content-Type": "application/json" } });
+        if (record.agentId !== auth.agentId) {
+            return FORBIDDEN("forbidden: cannot delete workspace state for another agent");
         }
         return super.delete(id);
     }

package/dist/resources/XAA.js

@@ -1,4 +1,5 @@
 import { databases } from "@harperfast/harper";
+import { allowAdmin } from "./agent-auth.js";
 import { createHash, randomBytes } from "node:crypto";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 /**
@@ -252,6 +253,13 @@ export async function handleJwtBearerGrant(data) {
  * Admin-only access.
  */
 export class IdpConfig extends databases.flair.IdpConfig {
+    // Admin-only on every path (the "Admin-only" comment was previously unenforced —
+    // a pure put() override with no auth check, so the non-rejecting gate let
+    // anonymous through to Harper's handler). allowAdmin permits admin + internal.
+    allowRead() { return allowAdmin(this.getContext?.()); }
+    allowCreate() { return allowAdmin(this.getContext?.()); }
+    allowUpdate() { return allowAdmin(this.getContext?.()); }
+    allowDelete() { return allowAdmin(this.getContext?.()); }
     async put(content) {
         const now = nowISO();
         content.enabled ??= true;

package/dist/resources/agent-auth.js

@@ -0,0 +1,209 @@
+/**
+ * flair-agent-auth — Ed25519 agent authentication.
+ *
+ * The verification logic that used to live in the instance-wide `server.http`
+ * auth-middleware, extracted into a per-resource helper. Resources call
+ * `verifyAgentRequest()` from their `allow*()` methods to identify + authorize
+ * the calling agent. This keeps flair's auth PER-RESOURCE (Harper-native) so it
+ * composes on a multi-component hub instead of a global gate that 401s siblings.
+ *
+ * Plugin-shaped on purpose (config via env today, extractable to a standalone
+ * @tps/agent-auth Harper plugin later — the "agent auth as its own plugin" path).
+ *
+ * Auth model: an agent presents `Authorization: TPS-Ed25519 <id>:<ts>:<nonce>:<sig>`.
+ * The signature covers `<id>:<ts>:<nonce>:<METHOD>:<pathname><search>` and is
+ * verified against the agent's stored Ed25519 public key. Replay is bounded by a
+ * 30s timestamp window + a per-(agent,nonce) seen-set pruned to that window.
+ */
+import { databases } from "@harperfast/harper";
+const WINDOW_MS = Number(process.env.FLAIR_AGENT_AUTH_WINDOW_MS) || 30_000;
+/**
+ * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
+ * `flair_agent` role), replacing the old admin super_user elevation. Single
+ * source of truth — the auth gate resolves agents to this user and the CLI
+ * provisions it (ensureFlairAgentUser); they MUST agree on the name.
+ */
+export const FLAIR_AGENT_USERNAME = "flair-agent";
+// Replay protection: remember recently-seen (agent:nonce), pruned by the window.
+const nonceSeen = new Map();
+// ─── Crypto helpers ───────────────────────────────────────────────────────────
+function b64ToArrayBuffer(b64) {
+    // Handle both standard and URL-safe base64.
+    const std = b64.replace(/-/g, "+").replace(/_/g, "/");
+    const bin = atob(std);
+    const buf = new ArrayBuffer(bin.length);
+    const view = new Uint8Array(buf);
+    for (let i = 0; i < bin.length; i++)
+        view[i] = bin.charCodeAt(i);
+    return buf;
+}
+const keyCache = new Map();
+async function importEd25519Key(publicKeyStr) {
+    const cached = keyCache.get(publicKeyStr);
+    if (cached)
+        return cached;
+    // Accept hex (64-char) or base64 (44-char) encoded 32-byte Ed25519 public key.
+    let raw;
+    if (/^[0-9a-f]{64}$/i.test(publicKeyStr)) {
+        const bytes = new Uint8Array(32);
+        for (let i = 0; i < 32; i++)
+            bytes[i] = parseInt(publicKeyStr.slice(i * 2, i * 2 + 2), 16);
+        raw = bytes.buffer;
+    }
+    else {
+        raw = b64ToArrayBuffer(publicKeyStr);
+    }
+    const key = await crypto.subtle.importKey("raw", raw, { name: "Ed25519" }, false, ["verify"]);
+    keyCache.set(publicKeyStr, key);
+    return key;
+}
+// ─── Admin resolution ─────────────────────────────────────────────────────────
+// Admin agents come from FLAIR_ADMIN_AGENTS (comma-separated) OR Agent records
+// with role === "admin". OR-combined, cached 60s. Distinct from Harper's
+// super_user — admin here gates flair-policy decisions (promotions, raw ops).
+let adminCacheExpiry = 0;
+let adminCache = new Set();
+async function getAdminAgents() {
+    const now = Date.now();
+    if (now < adminCacheExpiry)
+        return adminCache;
+    const fromEnv = (process.env.FLAIR_ADMIN_AGENTS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+    const fromDb = [];
+    try {
+        const results = await databases.flair.Agent.search([{ attribute: "role", value: "admin", condition: "equals" }]);
+        for await (const row of results)
+            if (row?.id)
+                fromDb.push(row.id);
+    }
+    catch { /* Agent table may be empty */ }
+    adminCache = new Set([...fromEnv, ...fromDb]);
+    adminCacheExpiry = now + 60_000;
+    return adminCache;
+}
+export async function isAdmin(agentId) {
+    return (await getAdminAgents()).has(agentId);
+}
+const HEADER_RE = /^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/;
+async function doVerify(request) {
+    const header = request?.headers?.get?.("authorization") ??
+        request?.headers?.asObject?.authorization ??
+        "";
+    const m = HEADER_RE.exec(header);
+    if (!m)
+        return null;
+    const [, agentId, tsRaw, nonce, signatureB64] = m;
+    const ts = Number(tsRaw);
+    const now = Date.now();
+    if (!Number.isFinite(ts) || Math.abs(now - ts) > WINDOW_MS)
+        return null;
+    // Prune expired nonces, then reject replays within the window.
+    for (const [k, t] of nonceSeen)
+        if (now - t > WINDOW_MS)
+            nonceSeen.delete(k);
+    const nonceKey = `${agentId}:${nonce}`;
+    if (nonceSeen.has(nonceKey))
+        return null;
+    const agent = await databases.flair.Agent.get(agentId).catch(() => null);
+    if (!agent?.publicKey)
+        return null;
+    // Canonical signed payload: id:ts:nonce:METHOD:pathname+search (must match the
+    // TPS CLI signer exactly — changing this breaks every agent's auth).
+    const url = new URL(request.url, "http://localhost");
+    const payload = `${agentId}:${tsRaw}:${nonce}:${request.method}:${url.pathname}${url.search}`;
+    try {
+        const key = await importEd25519Key(String(agent.publicKey));
+        const ok = await crypto.subtle.verify({ name: "Ed25519" }, key, b64ToArrayBuffer(signatureB64), new TextEncoder().encode(payload));
+        if (!ok)
+            return null;
+    }
+    catch {
+        return null;
+    }
+    nonceSeen.set(nonceKey, ts);
+    return { agentId, isAdmin: await isAdmin(agentId) };
+}
+/**
+ * Verify a TPS-Ed25519 signed request → the authenticated agent, or null.
+ *
+ * MEMOIZED per request object: `allow*` may run several times for one request,
+ * and re-running doVerify would (a) waste a crypto verify and (b) double-consume
+ * the nonce (the 2nd call would see a replay and fail). We verify once and cache
+ * the result (including null) on the request.
+ */
+export async function verifyAgentRequest(request) {
+    if (!request)
+        return null;
+    if (request._flairAgentAuth !== undefined)
+        return request._flairAgentAuth;
+    const result = await doVerify(request);
+    try {
+        request._flairAgentAuth = result;
+    }
+    catch { /* frozen request — fine, just no cache */ }
+    return result;
+}
+/**
+ * Three-way auth verdict for a resource — the safe replacement for the old
+ * `if (!authAgent) → unfiltered/trusted` pattern that leaked to anonymous callers
+ * once the gate stopped rejecting them. Distinguishes:
+ *   - **internal**: no HTTP request at all → a programmatic/in-process call
+ *     (maintenance, consolidation). Trusted; callers may run unfiltered.
+ *   - **agent**: a verified agent (Ed25519). Carries agentId + isAdmin.
+ *   - **anonymous**: an HTTP request with NO valid agent → MUST be denied.
+ *
+ * Pass the RESOURCE CONTEXT (`getContext()`), not `getContext().request`:
+ * `getContext().request` is inconsistently populated across resource methods
+ * (present for search/GET, undefined for PUT/POST in Table resources), so we read
+ * the gate's annotations off `context.request ?? context` — exactly how the
+ * pre-reshape resources read `request.tpsAgent`. Resolution order:
+ *   1. explicit anonymous marker (`tpsAnonymous`, set by the non-rejecting gate)
+ *   2. gate's verified-agent annotation (`tpsAgent` / `tpsAgentIsAdmin`)
+ *   3. per-agent identity on `context.user` (the de-elevated user; username=agentId)
+ *   4. header verify (custom-resource allow*, where the raw request is present)
+ *      — and if a request object IS present but yields no agent → anonymous
+ *   5. nothing at all → trusted internal call
+ */
+/**
+ * allow* for AGENT-FACING resources: permit verified agents, admins/super_user,
+ * and trusted internal calls; deny anonymous HTTP. Pass getContext(). Per-record
+ * scoping/ownership is still enforced in the handler. Replaces the
+ * `!!verifyAgentRequest(request)` pattern, which wrongly denied Basic-admin/
+ * super_user (no TPS header) — breaking the CLI/consolidation path.
+ */
+export async function allowVerified(context) {
+    return (await resolveAgentAuth(context)).kind !== "anonymous";
+}
+/**
+ * allow* for ADMIN-ONLY resources: permit admin agents + super_user + trusted
+ * internal calls; deny non-admin agents and anonymous.
+ */
+export async function allowAdmin(context) {
+    const a = await resolveAgentAuth(context);
+    return a.kind === "internal" || (a.kind === "agent" && a.isAdmin);
+}
+export async function resolveAgentAuth(context) {
+    const c = context?.request ?? context;
+    if (!c)
+        return { kind: "internal" };
+    if (c.tpsAnonymous === true)
+        return { kind: "anonymous" };
+    if (c.tpsAgent) {
+        return { kind: "agent", agentId: String(c.tpsAgent), isAdmin: c.tpsAgentIsAdmin === true };
+    }
+    const user = context?.user ?? c.user;
+    if (user?.role?.permission?.super_user === true) {
+        return { kind: "agent", agentId: String(user.username ?? "admin"), isAdmin: true };
+    }
+    if (user?.username && user.username !== FLAIR_AGENT_USERNAME) {
+        return { kind: "agent", agentId: String(user.username), isAdmin: false };
+    }
+    // A raw request with headers is present → verify it; an HTTP request that
+    // yields no agent is anonymous (NOT internal).
+    if (c.headers?.get || c.headers?.asObject) {
+        const auth = await verifyAgentRequest(c);
+        if (auth)
+            return { kind: "agent", agentId: auth.agentId, isAdmin: auth.isAdmin };
+        return { kind: "anonymous" };
+    }
+    return { kind: "internal" };
+}