@tpsdev-ai/flair 0.11.0 → 0.12.0

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" };
+}

package/dist/resources/auth-middleware.js

@@ -1,6 +1,7 @@
 import { patchRecord } from "./table-helpers.js";
 import { server, databases } from "@harperfast/harper";
 import { getEmbedding } from "./embeddings-provider.js";
+import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -31,34 +32,10 @@ function getAdminPass() {
 const WINDOW_MS = 30_000;
 const nonceSeen = new Map();
 // ─── Admin resolution ─────────────────────────────────────────────────────────
-// Admin agents: from FLAIR_ADMIN_AGENTS env var (comma-separated) OR
-// Agent records with role === "admin". Both sources are OR-combined.
-// Result is cached for 60s to avoid per-request DB hits.
-let adminCacheExpiry = 0;
-let adminCache = new Set();
-async function getAdminAgents() {
-    const now = Date.now();
-    if (now < adminCacheExpiry)
-        return adminCache;
-    const from_env = (process.env.FLAIR_ADMIN_AGENTS ?? "")
-        .split(",").map((s) => s.trim()).filter(Boolean);
-    let from_db = [];
-    try {
-        const results = await databases.flair.Agent.search([{ attribute: "role", value: "admin", condition: "equals" }]);
-        for await (const row of results) {
-            if (row?.id)
-                from_db.push(row.id);
-        }
-    }
-    catch { /* Agent table might not be populated yet */ }
-    adminCache = new Set([...from_env, ...from_db]);
-    adminCacheExpiry = now + 60_000;
-    return adminCache;
-}
-export async function isAdmin(agentId) {
-    const admins = await getAdminAgents();
-    return admins.has(agentId);
-}
+// `isAdmin` (FLAIR_ADMIN_AGENTS env + Agent role==="admin", 60s-cached) now lives
+// in agent-auth.ts as the single source of truth, imported above. During the
+// auth reshape this gate and the per-resource allow* helpers must agree on who's
+// an admin — one implementation guarantees they can't diverge.
 // ─── Crypto helpers ───────────────────────────────────────────────────────────
 function b64ToArrayBuffer(b64) {
     // Handle both standard and URL-safe base64
@@ -149,9 +126,20 @@ server.http(async (request, nextLayer) => {
         // (allowCreate=true on the Resource).
         url.pathname === "/Presence")
         return nextLayer(request);
-    // If Harper has already authorized this request (e.g. authorizeLocal=true on localhost),
-    // trust Harper's auth decision and pass through without requiring additional headers.
+    // If Harper has already authorized this request (e.g. Basic admin, or
+    // authorizeLocal=true on localhost), trust Harper's auth decision and pass
+    // through. Annotate the admin identity so resources' resolveAgentAuth recognizes
+    // this as an ADMIN caller (not anonymous) — otherwise a Basic-admin request,
+    // which carries no TPS-Ed25519 header, gets classified anonymous and denied.
     if (request.user?.role?.permission?.super_user === true) {
+        request.tpsAgent = request.user.username ?? "admin";
+        request.tpsAgentIsAdmin = true;
+        try {
+            request.headers.set("x-tps-agent", request.tpsAgent);
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-agent"] = request.tpsAgent;
+        }
+        catch { /* frozen headers — annotation on request object still applies */ }
         return nextLayer(request);
     }
     // Skip re-entry: if we already swapped auth to Basic, pass through
@@ -224,8 +212,19 @@ server.http(async (request, nextLayer) => {
                 }
             }
         }
-        catch { /* fall through to Ed25519 check */ }
-        return new Response(JSON.stringify({ error: "invalid_admin_credentials" }), { status: 401 });
+        catch { /* fall through to anonymous */ }
+        // NON-REJECTING (auth-rbac flip): a Basic header that matched no admin/super_user/
+        // pair path → annotate anonymous + pass through (don't 401 — a sibling component's
+        // Basic auth on a shared Harper must not be rejected by flair's gate). Resource
+        // allow* denies if the path is flair-protected.
+        request.tpsAnonymous = true;
+        try {
+            request.headers.set("x-tps-anonymous", "1");
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-anonymous"] = "1";
+        }
+        catch { /* frozen headers */ }
+        return nextLayer(request);
     }
     // ── Ed25519 agent auth ────────────────────────────────────────────────────
     const m = header.match(/^TPS-Ed25519\s+([^:]+):(\d+):([^:]+):(.+)$/);
@@ -244,7 +243,19 @@ server.http(async (request, nextLayer) => {
                 },
             });
         }
-        return new Response(JSON.stringify({ error: "missing_or_invalid_authorization" }), { status: 401 });
+        // NON-REJECTING GATE (auth-rbac flip): no valid agent → annotate anonymous and
+        // pass through. Per-resource allow* (resolveAgentAuth → anonymous → deny) is the
+        // enforcement; the gate no longer 401s instance-wide, which was breaking sibling
+        // components on a shared Harper / composite hub. Anonymous reaches only public
+        // allow-listed paths + resources whose allow* permit it.
+        request.tpsAnonymous = true;
+        try {
+            request.headers.set("x-tps-anonymous", "1");
+            if (request.headers.asObject)
+                request.headers.asObject["x-tps-anonymous"] = "1";
+        }
+        catch { /* frozen headers — annotation on the request object still applies */ }
+        return nextLayer(request);
     }
     const [, agentId, tsRaw, nonce, signatureB64] = m;
     const ts = Number(tsRaw);
@@ -277,33 +288,50 @@ server.http(async (request, nextLayer) => {
     request._tpsAuthVerified = true;
     request.tpsAgentIsAdmin = await isAdmin(agentId);
     // Grant Harper-level permissions for the cryptographically-verified agent by
-    // setting request.user directly to the admin super_user.
+    // setting request.user directly. Setting request.user is the supported
+    // extension path (and the only one that works post-5.0.9: Harper resolves
+    // request.user from the Authorization header BEFORE this middleware runs, and
+    // a TPS-Ed25519 header matches no Basic/Bearer strategy, so request.user
+    // arrives null — see #456). getUser(name, null) looks up the record WITHOUT
+    // password validation, safe here because the Ed25519 signature already proved
+    // identity cryptographically.
     //
-    // Prior approach swapped the Authorization header to "Basic admin:<pass>" so
-    // Harper's auth pipeline would re-authenticate with full (HNSW-capable)
-    // permissions. That silently broke under Harper 5.0.9: its authentication
-    // layer (security/auth.ts `authentication()`) reads the Authorization header
-    // and resolves request.user BEFORE invoking this middleware via nextHandler.
-    // A TPS-Ed25519 header matches no Basic/Bearer strategy, so Harper sets
-    // request.user = null and never re-reads the header — our post-hoc swap was
-    // ignored, the request ran unauthenticated, and Harper surfaced it downstream
-    // as a generic "Login failed" 401. (Broke at the 2026-05-27 daemon restart,
-    // which loaded 5.0.9 fresh; the prior long-running process held an older
-    // in-memory Harper where the late header read still worked.)
+    // RESHAPE (auth-rbac) — THE FLIP: per-agent DE-ELEVATION. A cryptographically-
+    // verified NON-admin agent resolves to the least-privilege `flair-agent` user,
+    // NOT admin super_user. The flair_agent role grants exactly the table CRUD agents
+    // need; with no operations grant, /sql + /graphql are natively 403 (the hand-
+    // rolled raw-query block below becomes belt-and-suspenders). Admins still resolve
+    // to admin. getUser(name, null) looks up WITHOUT password validation — safe
+    // because the Ed25519 signature already proved identity. Row-level ownership stays
+    // enforced via x-tps-agent / resolveAgentAuth, independent of request.user.
     //
-    // Setting request.user directly is the supported extension path and is honored
-    // by all downstream resources, including HNSW vector search. getUser(admin,
-    // null) looks up the admin record WITHOUT password validation — safe here
-    // because the Ed25519 signature verified above already proves agent identity
-    // cryptographically; no Basic credential is presented. This preserves the
-    // prior privilege model (verified agents act with admin perms; per-agent data
-    // isolation is still enforced downstream via the x-tps-agent header below).
+    // GRACEFUL FALLBACK: if the flair-agent user isn't provisioned on this instance
+    // yet (pre-migration — ensureFlairAgentUser hasn't run), fall back to admin so
+    // agents keep working. De-elevation activates per-instance once the user exists.
     try {
-        request.user = await server.getUser("admin", null, request);
+        if (request.tpsAgentIsAdmin) {
+            request.user = await server.getUser("admin", null, request);
+        }
+        else {
+            let deElevated = null;
+            try {
+                deElevated = await server.getUser(FLAIR_AGENT_USERNAME, null, request);
+            }
+            catch { /* not provisioned */ }
+            // getUser(name, null) returns a ROLE-LESS phantom `{ username }` (not null,
+            // not a throw) for a nonexistent user — harper security/user.js
+            // findAndValidateUser: `if (!userTmp) { if (!validatePassword) return { username } }`.
+            // A phantom is truthy, so `deElevated ?? admin` would keep it and the request
+            // would carry NO role → 403 AccessViolation. Require a real role to use the
+            // de-elevated user; otherwise fall back to admin (pre-migration instances).
+            request.user = (deElevated && deElevated.role)
+                ? deElevated
+                : await server.getUser("admin", null, request);
+        }
     }
     catch {
-        // Admin record unavailable — request proceeds as the verified tpsAgent
-        // without elevated perms; resource-level scoping still applies.
+        // No usable user record — request proceeds as the verified tpsAgent without
+        // elevated perms; resource-level scoping (x-tps-agent) still applies.
     }
     // Propagate authenticated agent to downstream resources via header.
     // Resources can read this to enforce agent-level scoping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",
   "license": "Apache-2.0",