@tpsdev-ai/flair 0.31.0 → 0.32.0

package/dist/resources/Agent.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
-import { resolveAgentAuth, allowVerified, allowAdmin } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { agentRecordIsAdmin, reconcileAdminFields } from "./agent-admin.js";
 import { localInstanceId } from "./instance-identity.js";
 /**
  * Agent resource — serves as the Principal table in 1.0.
@@ -34,10 +35,18 @@ export class Agent extends databases.flair.Agent {
         content.kind ||= "agent";
         content.status ||= "active";
         content.displayName ||= content.name;
-        content.admin ??= false;
-        // Trust tier defaults per kind
+        // flair#941 — the two admin fields are reconciled BEFORE anything derives
+        // from them, so `role` and `admin` agree on disk whichever one the caller
+        // used. Replaces `content.admin ??= false`, which defaulted the mirror
+        // without ever consulting the authority: a caller who passed role:"admin"
+        // got a record that was an admin at the gate and a non-admin to every
+        // reporter. allowCreate() is allowAdmin(), so this path is admin-only.
+        reconcileAdminFields(content);
+        // Trust tier defaults per kind — derived from the SAME predicate the gate
+        // uses, so an admin principal cannot land on the non-admin default just
+        // because the caller spelled admin the other way.
         if (!content.defaultTrustTier) {
-            content.defaultTrustTier = content.admin ? "endorsed" : "unverified";
+            content.defaultTrustTier = agentRecordIsAdmin(content) ? "endorsed" : "unverified";
         }
         content.createdAt = now;
         content.updatedAt = now;
@@ -51,7 +60,25 @@ export class Agent extends databases.flair.Agent {
         }
         return super.post(content, context);
     }
-    async put(content) {
+    /**
+     * Authorization shared by BOTH mutation paths (PUT → put, PATCH → patch).
+     *
+     * It lives in one place because it previously lived only in put(), and PATCH
+     * does not route through put() — so every rule written here was enforced on
+     * one verb and not the other. Returns a Response to send, or null to proceed.
+     *
+     * Two rules:
+     *   1. Only an admin principal may modify a principal OTHER than itself.
+     *   2. Only an admin principal may change a principal's ADMIN STATUS — on any
+     *      record, including the caller's own. Rule 1 alone never covered this:
+     *      an agent editing its own record is inside its rights for ordinary
+     *      fields (runtime, displayName, subjects) and must not be for the fields
+     *      that decide whether it is an administrator.
+     *
+     * `internal` (in-process maintenance, federation merge) and admin agents pass
+     * through unchanged.
+     */
+    async authorizePrincipalWrite(content) {
         const auth = await resolveAgentAuth(this.getContext?.());
         // Anonymous denied (defense-in-depth alongside allowUpdate; the old check read
         // tpsAgent and treated a missing agent as trusted, so anonymous slipped through).
@@ -60,24 +87,91 @@ export class Agent extends databases.flair.Agent {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
-        // Only admin principals can modify OTHER principals; an agent updates its own.
-        if (auth.kind === "agent" && !auth.isAdmin) {
-            const existing = await super.get();
-            if (existing && existing.id !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+        if (auth.kind !== "agent" || auth.isAdmin)
+            return null;
+        const existing = await Promise.resolve(super.get()).catch(() => null);
+        // 1. Only admin principals can modify OTHER principals.
+        if (existing && existing.id !== auth.agentId) {
+            return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        // 2. Only admin principals can change admin status. Compare the RESULTING
+        // status against the stored one so an ordinary self-update that simply
+        // doesn't mention either field is unaffected, and a no-op restatement of
+        // the caller's existing status is not a spurious denial.
+        const touchesPrivilegeFields = content != null && typeof content === "object" && ("role" in content || "admin" in content);
+        if (touchesPrivilegeFields) {
+            const merged = { ...(existing ?? {}), ...content };
+            const wouldBeAdmin = agentRecordIsAdmin(merged) || merged.admin === true;
+            const isAdminNow = agentRecordIsAdmin(existing) || (existing?.admin === true);
+            if (wouldBeAdmin !== isAdminNow) {
+                return new Response(JSON.stringify({ error: "only admin principals can change a principal's admin status" }), {
                     status: 403, headers: { "content-type": "application/json" },
                 });
             }
         }
+        return null;
+    }
+    async put(content) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
         content.updatedAt = new Date().toISOString();
         // Protect immutable fields
         delete content.createdAt;
         delete content.publicKey; // key rotation goes through dedicated endpoint
+        // Keep the two admin fields agreeing on disk — see resources/agent-admin.ts.
+        // Only an admin can have reached here with a privilege change (see
+        // authorizePrincipalWrite), so this normalises an authorized intent; it
+        // never manufactures one.
+        reconcileAdminFields(content);
         // Write-time originatorInstanceId stamp — see post() above / Memory.ts's
         // stampOriginatorInstanceId doc. No-op if already set.
         if (content.originatorInstanceId == null) {
             content.originatorInstanceId = await localInstanceId();
         }
-        return super.put(content);
+        const result = await super.put(content);
+        invalidateAdminCache();
+        return result;
+    }
+    /**
+     * PATCH → Harper's partial update (`Resource.patch(data, query)`; see
+     * harper/dist/server/REST.js's method switch and Resource.js's static patch).
+     *
+     * This override exists because there was none. Every per-record authorization
+     * rule this resource enforces was written in put(), and PATCH does not route
+     * through put() — so none of those rules ran on a PATCH. allowUpdate() is
+     * allowVerified(), which means the only check a PATCH ever met was "are you
+     * some verified agent"; the rules that make the principal table safe (you may
+     * only edit yourself; you may not change your own admin status) were not
+     * among them.
+     *
+     * That is the shape flair#941 keeps running into: a check that reads as
+     * complete because it exists, and simply is not on the path the caller took.
+     * Both verbs now share authorizePrincipalWrite().
+     */
+    async patch(content, query) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
+        if (content != null && typeof content === "object") {
+            // A partial update must not be able to leave the record's two admin
+            // fields disagreeing, so reconcile against the MERGED result rather than
+            // the patch alone — patching only `role` has to carry the mirror with it.
+            if ("role" in content || "admin" in content) {
+                const existing = await Promise.resolve(super.get()).catch(() => null);
+                const merged = reconcileAdminFields({ ...(existing ?? {}), ...content });
+                content.role = merged.role;
+                content.admin = merged.admin;
+            }
+            // Immutable fields, matching put().
+            delete content.createdAt;
+            delete content.publicKey;
+            content.updatedAt = new Date().toISOString();
+        }
+        const result = await super.patch(content, query);
+        invalidateAdminCache();
+        return result;
     }
 }

package/dist/resources/AgentSeed.js

@@ -17,7 +17,8 @@
  * Auth: admin only.
  */
 import { Resource, databases } from "harper";
-import { isAdmin, allowAdmin } from "./agent-auth.js";
+import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { reconcileAdminFields } from "./agent-admin.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -62,8 +63,15 @@ export class AgentSeed extends Resource {
         const existingAgent = await databases.flair.Agent.get(agentId).catch(() => null);
         let agent = existingAgent;
         if (!existingAgent) {
-            agent = { id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now };
+            // flair#941 — this writes the RAW table, so resources/Agent.ts's post()
+            // never runs and its field reconciliation does not apply here. Seeding
+            // role:"admin" without the mirror was the one path in the product that
+            // produced a genuine administrator every reporter displayed as an
+            // ordinary agent. Admin-only path (allowCreate + the isAdmin re-check
+            // above), so this normalises an authorized intent.
+            agent = reconcileAdminFields({ id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now });
             await databases.flair.Agent.put(agent);
+            invalidateAdminCache();
         }
         // ── Soul entries ──────────────────────────────────────────────────────────
         const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);

package/dist/resources/MemoryUsage.js

@@ -95,6 +95,24 @@ export class MemoryUsage extends databases.flair.MemoryUsage {
             return super.put(content);
         return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
     }
+    /**
+     * PATCH — same rule as put(), because this ledger's invariant is IMMUTABILITY,
+     * not ownership.
+     *
+     * The shared record-ownership guard (resources/record-owner-guard.ts) covers
+     * this table for cross-agent writes, but it cannot express this rule: it
+     * permits an agent to modify a row it owns, and here even the OWNER must not.
+     * Measured before this override existed: the owning agent rewrote its own
+     * row's attribution with a PATCH and got 204, because Harper routes PATCH to
+     * patch() and put()'s check never ran. A resource whose rule is stricter than
+     * "you own it" still has to say so on every verb.
+     */
+    async patch(content, query) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.patch(content, query);
+        return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
+    }
     async delete(id) {
         const auth = await resolveAgentAuth(this.getContext?.());
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))

package/dist/resources/Presence.js

@@ -32,6 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } from "./agent-auth.js";
+import { agentRecordIsAdmin } from "./agent-admin.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
@@ -348,7 +349,13 @@ export class Presence extends databases.flair.Presence {
                 const entry = {
                     id: agentId,
                     displayName: agent?.displayName ?? agent?.name ?? agentId,
-                    role: agent?.role ?? "agent",
+                    // `role` is a human label on a PUBLIC roster (allowRead() is `true`),
+                    // and it is also the field that decides administrator status
+                    // (resources/agent-admin.ts). Publishing the admin sentinel would
+                    // hand an unauthenticated reader the list of privileged principals —
+                    // so the roster reports admins as ordinary agents. It is a display
+                    // label here and nothing authorizes on it (flair#941).
+                    role: agentRecordIsAdmin(agent) ? "agent" : (agent?.role ?? "agent"),
                     runtime: agent?.runtime ?? null,
                     // Current activity — only truthful while fresh; "idle" once decayed.
                     activity: activityFresh ? rawActivity : "idle",

package/dist/resources/agent-admin.js

@@ -0,0 +1,149 @@
+/**
+ * agent-admin.ts — the ONE answer to "is this principal an administrator?".
+ *
+ * The Agent (Principal) record carries two fields that both read as if they
+ * answered that question:
+ *
+ *   role: String       — administrator when the value is exactly "admin"
+ *   admin: Boolean     — "admin principals can manage other principals"
+ *
+ * They used to be consulted by DIFFERENT consumers, which is the whole defect
+ * (flair#941):
+ *
+ *   - resources/agent-auth.ts's isAdmin() — the single gate behind allowAdmin(),
+ *     and therefore behind every admin-only resource — searched `role` and
+ *     ignored `admin` completely.
+ *   - resources/mcp-handler.ts OR-ed the two together.
+ *   - Every reporter (flair principal show/list, the admin dashboard) displayed
+ *     `admin`, and every writer except AgentSeed wrote `admin`.
+ *
+ * So the field the product wrote and displayed was not the field the gate read.
+ * `flair principal add --admin` stored `admin: true` and granted nothing, while
+ * the dashboard confidently printed "admin: yes" for a principal that
+ * allowAdmin() rejects. Both directions are silent, and one of them is silent in
+ * the direction that flatters the operator.
+ *
+ * ─── The rule ────────────────────────────────────────────────────────────────
+ *
+ * `role === ADMIN_ROLE` is the AUTHORITY. `admin` is a SERVER-MAINTAINED MIRROR
+ * of it and is never read to reach an authorization decision again.
+ *
+ * Every decider and every reporter calls {@link agentRecordIsAdmin}, so no two
+ * surfaces can answer this question differently. Every write through a flair
+ * write path calls {@link reconcileAdminFields}, so a record that says one thing
+ * in one field and the opposite in the other cannot be STORED by any path flair
+ * offers.
+ *
+ * ─── Why `role` is the authority and not `admin` ─────────────────────────────
+ *
+ * `admin: Boolean` is honestly the better-shaped field: typed, indexed,
+ * unambiguous, and already the one every creation path and every UI uses.
+ * Making it the authority would nonetheless GRANT admin, on the primary HTTP
+ * gate, to every record that currently carries `admin: true` with a non-admin
+ * `role` — the records `flair principal add --admin` has been producing all
+ * along, which have never been admins. That is a widening of live access as a
+ * side effect of a consistency fix, decided by data nobody has audited. Keeping
+ * `role` as the authority changes no existing principal's rights on the gate:
+ * every principal that is an admin today is an admin after this change, and
+ * every principal that is not, is not.
+ *
+ * Switching the authority to `admin` is a reasonable follow-up, but it is a
+ * deliberate privilege migration with an audit of existing records — not
+ * something to slip in underneath a naming fix.
+ *
+ * ─── Records that already carry a mismatch ───────────────────────────────────
+ *
+ * Nothing is rewritten in bulk; no migration runs. What happens to each shape:
+ *
+ *   role:"admin" + admin:false|absent  — an admin today, an admin after. The
+ *     mirror is stale, so the CLI and dashboard used to report "not an admin"
+ *     for a principal holding admin rights; they now report the truth. The
+ *     stored mirror is repaired the next time the record is written through the
+ *     Agent resource.
+ *
+ *   admin:true + role not "admin"  — NOT an admin today on the gate, and not
+ *     after. This is what `flair principal add --admin` produced. The CLI and
+ *     dashboard used to report "admin: yes"; they now report the truth, which is
+ *     how an operator finds out the grant never took. The remedy is to re-issue
+ *     the grant (which now writes both fields). The one behaviour that does
+ *     change is the native MCP surface, which used to honour this field on its
+ *     own — see resources/mcp-handler.ts. That surface is gated behind
+ *     FLAIR_MCP_OAUTH and is default-OFF, so no instance running the shipped
+ *     defaults is affected.
+ *
+ * Deliberately dependency-free — pure predicates over a plain record, importing
+ * neither `harper` nor any resource, so the auth gate, the resources, the
+ * reporters and the tests can all share it without an import cycle.
+ */
+/** The exact `role` value that denotes a flair administrator. */
+export const ADMIN_ROLE = "admin";
+/**
+ * THE admin predicate. Every authorization decision and every report of a
+ * principal's admin status resolves through this one function.
+ *
+ * Total over every field combination: a record with a contradictory `admin`
+ * mirror gets the SAME answer here as it does at the gate, so a contradiction
+ * can never produce two different answers on two different surfaces. It is
+ * deliberately NOT an OR over the two fields — see the module header.
+ *
+ * Note this covers Agent RECORDS only. `FLAIR_ADMIN_AGENTS` is a separate,
+ * env-configured admin source union-ed in by resources/agent-auth.ts's
+ * getAdminAgents(); it names agent ids and never touches a record.
+ */
+export function agentRecordIsAdmin(record) {
+    return record?.role === ADMIN_ROLE;
+}
+/**
+ * Make a record about to be written self-consistent, so the two fields can
+ * never be STORED disagreeing.
+ *
+ * Admin is requested by EITHER spelling — `role: "admin"` or `admin: true` —
+ * because both have been documented and both are what an operator reaches for.
+ * Whichever they used, both fields come out of here agreeing. That is what
+ * makes `flair principal add --admin` finally do what it says: it writes the
+ * Boolean, and the Boolean now carries the record into the authority field.
+ *
+ * **Honouring `admin: true` here is not a privilege widening.** Every call site
+ * is already admin-gated — Agent.post() is allowCreate()=allowAdmin, Agent's
+ * update path refuses a privilege change from a non-admin, and AgentSeed is
+ * admin-only and re-checks. A caller that can reach this could have written
+ * `role: "admin"` directly; this only means they no longer have to know which
+ * of the two fields is the real one.
+ *
+ * A non-admin `role` is free text (a human label — "researcher", "COO") and is
+ * left exactly as supplied; only the admin sentinel is normalised.
+ *
+ * Mutates `content` in place and returns it, matching the surrounding
+ * defaults-stamping style in resources/Agent.ts's post().
+ */
+export function reconcileAdminFields(content) {
+    if (!content || typeof content !== "object")
+        return content;
+    // Widened locally: `content` is generic so TypeScript will not accept writes
+    // to named properties on it, but the whole point here is to normalise those
+    // two properties in place and hand the caller back its own object.
+    const record = content;
+    if (record.role === ADMIN_ROLE || record.admin === true) {
+        record.role = ADMIN_ROLE;
+        record.admin = true;
+    }
+    else {
+        record.admin = false;
+    }
+    return content;
+}
+/**
+ * True when a stored record's two fields disagree — i.e. it was written by
+ * something other than a flair write path (a raw table write, an ops-API
+ * insert, a federation merge) and now claims one thing to a reader of `admin`
+ * and the opposite to the gate.
+ *
+ * Reporting-only. Nothing authorizes on this; it exists so a surface can SAY
+ * that a record is inconsistent instead of silently picking a side.
+ */
+export function adminFieldsDisagree(record) {
+    const r = record;
+    if (!r || typeof r !== "object")
+        return false;
+    return agentRecordIsAdmin(r) !== (r.admin === true);
+}

package/dist/resources/agent-auth.js

@@ -17,6 +17,7 @@
  */
 import { databases } from "harper";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
+import { ADMIN_ROLE, agentRecordIsAdmin } from "./agent-admin.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -32,8 +33,14 @@ export const FLAIR_AGENT_USERNAME = "flair-agent";
 // visible to the other two, and the crypto/decoder logic can't drift.
 // ─── 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).
+// whose `role` is the admin sentinel. OR-combined, cached 60s. Distinct from
+// Harper's super_user — admin here gates flair-policy decisions (promotions,
+// raw ops).
+//
+// The record half of that union is the ONE place the Agent table is consulted
+// for an authorization decision, and it resolves through
+// resources/agent-admin.ts's shared predicate so it cannot drift from the
+// reporters or from the MCP surface (flair#941 — they had drifted).
 let adminCacheExpiry = 0;
 let adminCache = new Set();
 async function getAdminAgents() {
@@ -43,9 +50,9 @@ async function getAdminAgents() {
     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" }]);
+        const results = await databases.flair.Agent.search([{ attribute: "role", value: ADMIN_ROLE, condition: "equals" }]);
         for await (const row of results)
-            if (row?.id)
+            if (row?.id && agentRecordIsAdmin(row))
                 fromDb.push(row.id);
     }
     catch { /* Agent table may be empty */ }
@@ -53,6 +60,28 @@ async function getAdminAgents() {
     adminCacheExpiry = now + 60_000;
     return adminCache;
 }
+/**
+ * Drop the memoised admin set so the NEXT isAdmin() re-reads the Agent table.
+ *
+ * The 60s TTL is a load optimisation, but on its own it makes a privilege
+ * change take up to a minute to appear — which reads as "the change didn't
+ * work", and is exactly the confusion flair#941 is about: an operator grants
+ * admin, tests it, sees a denial, and starts changing other things. The write
+ * path knows precisely when a principal's admin status changed, so it says so
+ * and the grant is effective on the caller's very next request.
+ *
+ * Deliberately NOT a distributed invalidation: Harper runs N worker threads,
+ * each with its own module instance and its own cache, so a promotion applied
+ * on thread A still takes up to the TTL to be seen by thread B. Making that
+ * exact would mean a shared invalidation channel, which is a much larger change
+ * than the confusion warrants — the bound stays 60s, unchanged, and the common
+ * single-threaded/dev case becomes immediate. Called by resources/Agent.ts's
+ * write paths.
+ */
+export function invalidateAdminCache() {
+    adminCacheExpiry = 0;
+    adminCache = new Set();
+}
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
@@ -195,10 +224,73 @@ export async function allowAdmin(context) {
     const a = await resolveAgentAuth(context);
     return a.kind === "internal" || (a.kind === "agent" && a.isAdmin);
 }
+/**
+ * flair#936 — the `internal` verdict is TRUSTED and UNFILTERED, and it is also
+ * what a caller gets for supplying no context at all. Nothing distinguishes
+ * "I am flair's own maintenance code" from "I am an application developer who
+ * did not know a context was required": both spell it `new Memory()`, both
+ * succeed, and both return plausible data. It surfaces months later as memories
+ * that were never scoped.
+ *
+ * This does not change the verdict — every authorization outcome is byte-
+ * identical — it ends the SILENCE. A deliberate elevated call says so with
+ * `internalContext()` (resources/in-process.ts), whose `__flairInternal` marker
+ * is read here and nowhere else; anything else that lands on `internal` gets one
+ * warning per process, with the stack, so the condition is observable where it
+ * was previously invisible.
+ *
+ * MEASURED, and the reason this is worth having: flair itself has NO in-process
+ * caller that relies on the omission — every maintenance, migration, federation
+ * and boot path goes through the raw `databases.flair.*` table accessor, which
+ * bypasses this resolver entirely rather than defaulting through it. So a
+ * warning from this line is, in practice, always either an embedding
+ * application that forgot a context or a flair call site that should be naming
+ * its intent. Neither is noise.
+ *
+ * The marker is read off `context`, NOT off `c`: `c` is rebound to
+ * `context.request` on the line below, and internalContext() carries the marker
+ * on the outer object.
+ */
+let warnedInternalByOmission = false;
+/**
+ * Was this elevated call DELIBERATE — i.e. did the caller name the authority
+ * with `internalContext()` rather than land on it by leaving a context off?
+ *
+ * Exported because it is the whole decision, and a decision worth testing is
+ * worth testing directly: the warning itself is latched once per process, which
+ * makes any test of the side effect order-dependent (bun shares one module
+ * registry across the whole run, so whichever file resolves a context-less call
+ * first consumes the latch and every later assertion silently passes). Pinning
+ * the predicate instead is deterministic.
+ *
+ * Grants nothing and is never consulted for an authorization decision — the
+ * verdict is identical either way.
+ */
+export function isDeliberateInternalCall(context) {
+    return context?.__flairInternal === true;
+}
+/** The advisory text, exported so its content is pinned without tripping the latch. */
+export const INTERNAL_BY_OMISSION_WARNING = "[flair-auth] a resource was invoked with NO caller context and resolved to the trusted " +
+    "`internal` verdict: reads are UNFILTERED across every agent, writes are unattributed, and " +
+    "the admin-only gate passes. If this is your application's code, pass agentContext(<id>) from " +
+    "@tpsdev-ai/flair's in-process seam so the call is scoped and attributed. If the elevated " +
+    "authority is genuinely intended, say so with internalContext() and this warning will stop. " +
+    "Fires once per process.";
+function noteInternalVerdict(context) {
+    if (warnedInternalByOmission)
+        return;
+    if (isDeliberateInternalCall(context))
+        return; // deliberate, and said so
+    warnedInternalByOmission = true;
+    const stack = (new Error().stack ?? "").split("\n").slice(2, 7).join("\n");
+    console.error(INTERNAL_BY_OMISSION_WARNING + "\n" + stack);
+}
 export async function resolveAgentAuth(context) {
     const c = context?.request ?? context;
-    if (!c)
+    if (!c) {
+        noteInternalVerdict(context);
         return { kind: "internal" };
+    }
     if (c.tpsAnonymous === true)
         return { kind: "anonymous" };
     if (c.tpsAgent) {
@@ -231,5 +323,6 @@ export async function resolveAgentAuth(context) {
             return { kind: "agent", agentId: auth.agentId, isAdmin: auth.isAdmin };
         return { kind: "anonymous" };
     }
+    noteInternalVerdict(context);
     return { kind: "internal" };
 }