neotoma 0.7.0 → 0.8.0

package/dist/actions.d.ts

@@ -14,6 +14,80 @@ export declare const app: import("express-serve-static-core").Express;
  * X-Forwarded-For header — any caller can claim to be loopback.
  */
 export declare function isLocalRequest(req: express.Request): boolean;
+/**
+ * Derive the canonical `@authority` the AAuth profile requires (AAuth §10.3.1).
+ * We trust explicit configuration first, then fall back to the host the
+ * process is actually listening on. We must NOT trust `Host:` headers from
+ * the request path — an attacker could smuggle signatures authored against
+ * a different authority. See src/middleware/aauth_verify.ts.
+ */
+export declare function canonicalAauthAuthority(): string;
+export declare function storeStructuredForApi(params: {
+    userId: string;
+    entities: Record<string, unknown>[];
+    sourcePriority: number;
+    observationSource?: import("./shared/action_schemas.js").ObservationSource;
+    idempotencyKey: string;
+    originalFilename?: string;
+    relationships?: Array<{
+        relationship_type: string;
+        source_index: number;
+        target_index: number;
+    }>;
+    commit?: boolean;
+    strict?: boolean;
+}): Promise<{
+    success: boolean;
+    replayed: boolean;
+    source_id: any;
+    entities_created: number;
+    observations_created: number;
+    entities: {
+        entity_id: string;
+        entity_type: string;
+        observation_id: string;
+    }[];
+} | {
+    warnings?: {
+        code: string;
+        policy: string;
+        observation_index: number;
+        entity_type: string;
+        entity_id: string;
+        identity_basis: string;
+        identity_rule: string;
+    }[] | undefined;
+    success: boolean;
+    replayed: boolean;
+    commit: boolean;
+    source_id: string | null;
+    entities_created: number;
+    observations_created: number;
+    entities: {
+        entity_id: string;
+        entity_type: string;
+        observation_id: string | null;
+        observation_index: number;
+        action: "created" | "matched_existing" | "would_create" | "would_match_existing" | "extended";
+        canonical_name: string;
+        resolver_path: string[];
+        identity_basis: string;
+        identity_rule: string;
+        warnings?: {
+            code: string;
+            policy: string;
+            entity_type: string;
+            identity_basis: string;
+            identity_rule: string;
+        }[] | undefined;
+        entity_snapshot_after: Record<string, unknown> | null;
+    }[];
+    relationships_created: {
+        relationship_type: string;
+        source_entity_id: string;
+        target_entity_id: string;
+    }[];
+}>;
 export declare function startHTTPServer(): Promise<{
     server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse>;
     port: number;

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AA0I9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAgY7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA2hMD,wBAAsB,eAAe;;;eAkDpC"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAiJ9B,eAAO,MAAM,GAAG,6CAAY,CAAC;AAwZ7B;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAU5D;AA4PD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAmBhD;AA2kHD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,OAAO,4BAA4B,EAAE,iBAAiB,CAAC;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,KAAK,CAAC;QACpB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;;;;;;;;;;;;;cAkfS,MAAM;gBACJ,MAAM;2BACK,MAAM;qBACZ,MAAM;mBACR,MAAM;wBACD,MAAM;uBACP,MAAM;;;;;;;;;mBA9IV,MAAM;qBACJ,MAAM;wBACH,MAAM,GAAG,IAAI;2BACV,MAAM;;wBAET,MAAM;uBACP,MAAM,EAAE;wBACP,MAAM;uBACP,MAAM;;kBA9NX,MAAM;oBACJ,MAAM;yBACD,MAAM;4BACH,MAAM;2BACP,MAAM;;+BA4NF,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;;;2BAkFlC,MAAM;0BACP,MAAM;0BACN,MAAM;;GA8E3B;AA29DD,wBAAsB,eAAe;;;eA6EpC"}

package/dist/actions.js

@@ -16,11 +16,13 @@ import { encryptResponseMiddleware } from "./middleware/encrypt_response.js";
 import { unknownFieldsGuard } from "./middleware/unknown_fields_guard.js";
 import { aauthVerify, getAAuthContextFromRequest, getAttributionDecisionFromRequest, } from "./middleware/aauth_verify.js";
 import { attributionContext } from "./middleware/attribution_context.js";
+import { aauthAdmission, getAAuthAdmissionFromRequest, } from "./middleware/aauth_admission.js";
 import { buildSessionInfo } from "./services/session_info.js";
 import { AttributionPolicyError } from "./services/attribution_policy.js";
 import { registerFeedbackAdminProxyRoutes } from "./services/feedback/admin_proxy.js";
 import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
-import { getCurrentAgentIdentity, runWithRequestContext, } from "./services/request_context.js";
+import { getCurrentAAuthAdmission, getCurrentAgentIdentity, runWithRequestContext, } from "./services/request_context.js";
+import { assertCanWriteProtectedBatch } from "./services/protected_entity_types.js";
 import { createAgentIdentity as buildAgentIdentity, getAgentIdentityFromRequest, normaliseClientName, } from "./crypto/agent_identity.js";
 import { initServerKeys } from "./services/encryption_service.js";
 import { storeRawContent, downloadRawContent, resolveLocalSourceFilePath, SourceFileNotFoundError, } from "./services/raw_storage.js";
@@ -30,7 +32,7 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { NeotomaServer } from "./server.js";
 import { logger } from "./utils/logger.js";
 import { OAuthError } from "./services/mcp_oauth_errors.js";
-import { ensureLocalDevUser, ensureSandboxPublicUser, LOCAL_DEV_USER_ID, SANDBOX_PUBLIC_USER_ID, } from "./services/local_auth.js";
+import { ensureLocalDevUser, ensureSandboxAauthUser, ensureSandboxPublicUser, LOCAL_DEV_USER_ID, SANDBOX_PUBLIC_USER_ID, } from "./services/local_auth.js";
 import { isSandboxMode, sandboxDestructiveGuard, sandboxHeaderMiddleware, } from "./services/sandbox_mode.js";
 import { buildLandingContext, buildRootLandingHtml, buildRootLandingJson, buildRootLandingMarkdown, buildRobotsTxt, wantsHtml as acceptWantsHtml, wantsMarkdown as acceptWantsMarkdown, } from "./services/root_landing/index.js";
 import { getSandboxTermsResponse } from "./services/sandbox/terms.js";
@@ -363,6 +365,28 @@ app.get("/.well-known/oauth-protected-resource", async (req, res) => {
         authorization_servers: [base],
     });
 });
+// AAuth resource server metadata. Exposed publicly so AAuth client libraries
+// can auto-configure issuer / supported algs / signature window without an
+// out-of-band conversation. Neotoma is verifier-only: it never hosts agent
+// JWKs, so jwks_uri is null and agents convey their public keys per-request
+// via the Signature-Key header (with thumbprint binding via the jkt claim).
+// See docs/proposals/agent-trust-framework.md and src/middleware/aauth_verify.ts.
+app.get("/.well-known/aauth-resource.json", (_req, res) => {
+    const authorityHost = canonicalAauthAuthority();
+    const issuer = authorityHost.startsWith("http")
+        ? authorityHost
+        : `https://${authorityHost}`;
+    res.setHeader("Content-Type", "application/json");
+    res.json({
+        issuer,
+        client_name: "Neotoma",
+        signature_window: 60,
+        supported_algs: ["ES256", "EdDSA"],
+        supported_typ: ["aa-agent+jwt"],
+        jwks_uri: null,
+        jwks_uri_reason: "Neotoma is verifier-only; agent JWKs are conveyed per-request via the Signature-Key header (with thumbprint binding via the jkt claim).",
+    });
+});
 // Server info endpoint (no-auth) - exposes server port for MCP configuration
 // When NEOTOMA_MCP_PROXY_URL or MCP_PROXY_URL is set (e.g. ngrok tunnel), mcpUrl uses it so "Add to Cursor" uses the proxy.
 app.get("/server-info", (_req, res) => {
@@ -661,10 +685,20 @@ function setOAuthKeySessionCookie(req, res) {
  * the request path — an attacker could smuggle signatures authored against
  * a different authority. See src/middleware/aauth_verify.ts.
  */
-function canonicalAauthAuthority() {
+export function canonicalAauthAuthority() {
     const explicit = process.env.NEOTOMA_AAUTH_AUTHORITY?.trim();
-    if (explicit)
+    if (explicit) {
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(explicit)) {
+            try {
+                const url = new URL(explicit);
+                return url.host;
+            }
+            catch {
+                return explicit;
+            }
+        }
         return explicit;
+    }
     try {
         const url = new URL(config.apiBase);
         return url.host;
@@ -693,6 +727,13 @@ app.use(aauthVerify({
 // may nest a more specific `runWithRequestContext` — nested scopes
 // shadow outer ones exactly as intended.
 app.use(attributionContext());
+// Stronger AAuth Admission plan: resolve verified AAuth identities to
+// `agent_grant` entities and stamp `req.aauthAdmission` /
+// `req.authenticatedUserId`. Runs after attributionContext so the
+// admission middleware can nest a richer request context (admission +
+// identity) for downstream guards. Cheap public discovery routes are
+// short-circuited inside the middleware.
+app.use(aauthAdmission());
 // MCP StreamableHTTP endpoint (GET, POST, DELETE)
 // This endpoint enables Cursor's "Connect" button for OAuth authentication
 app.all("/mcp", async (req, res) => {
@@ -742,7 +783,12 @@ app.all("/mcp", async (req, res) => {
                 }
             }
         }
-        const hasAuth = !!(authHeader?.startsWith("Bearer ") || connectionIdHeader);
+        // Stronger AAuth Admission: a verified AAuth identity that resolves
+        // to an active `agent_grant` for some user is a valid remote auth
+        // path. Bearer / OAuth / X-Connection-Id remain fully supported.
+        const aauthAdmissionForRequest = getAAuthAdmissionFromRequest(req);
+        const aauthAdmitted = !!(aauthAdmissionForRequest && aauthAdmissionForRequest.admitted);
+        const hasAuth = !!(authHeader?.startsWith("Bearer ") || connectionIdHeader || aauthAdmitted);
         // When encryption is on, only the key-derived token is accepted
         if (config.encryption.enabled && connectionIdHeader !== "dev-local") {
             const wwwAuthHeader = `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource"`;
@@ -1763,6 +1809,20 @@ app.use(async (req, res, next) => {
     // full AAuth roundtrip get their hardware/software tier. Destructive admin
     // routes are separately gated by sandboxDestructiveGuard.
     if (isSandboxMode() && !headerAuth.startsWith("Bearer ")) {
+        // α (sandbox attribution partitioning): when the request carries a verified
+        // AAuth signature, attribute writes/reads to a deterministic per-thumbprint
+        // user instead of the shared SANDBOX_PUBLIC_USER_ID. Same key on two
+        // requests resolves to the same user_id; different keys → different
+        // user_ids. Unsigned requests keep the public-user fallback unchanged.
+        // Read partitioning falls out automatically because every read path scopes
+        // queries by req.authenticatedUserId.
+        const aauthCtx = req.aauth;
+        if (aauthCtx?.verified === true && typeof aauthCtx.thumbprint === "string") {
+            const aauthUser = ensureSandboxAauthUser(aauthCtx.thumbprint);
+            req.authenticatedUserId = aauthUser.id;
+            logger.info(`[Auth] ${req.method} ${req.path} auth_method=sandbox_aauth user_id=${aauthUser.id} thumbprint=${aauthCtx.thumbprint}`);
+            return next();
+        }
         const sandboxUser = ensureSandboxPublicUser();
         req.authenticatedUserId = sandboxUser.id;
         logger.info(`[Auth] ${req.method} ${req.path} auth_method=sandbox_public user_id=${sandboxUser.id}`);
@@ -1800,10 +1860,27 @@ app.use(async (req, res, next) => {
             }
         }
     }
+    // Stronger AAuth Admission: a verified AAuth identity that resolved
+    // to an active `agent_grant` is a valid remote auth path. The
+    // admission middleware has already populated `req.aauthAdmission`
+    // and `req.authenticatedUserId`. We accept it here even when no
+    // Bearer is present so agents holding an active grant can reach
+    // direct write routes (`/store`, `/observations/create`,
+    // `/create_relationship`, `/correct`) without OAuth/Bearer.
+    const admissionForRequest = getAAuthAdmissionFromRequest(req);
+    if (admissionForRequest?.admitted &&
+        admissionForRequest.user_id &&
+        req.authenticatedUserId === admissionForRequest.user_id) {
+        logger.info(`[Auth] ${req.method} ${req.path} auth_method=aauth_admitted user_id=${admissionForRequest.user_id} grant_id=${admissionForRequest.grant_id ?? "?"}`);
+        return next();
+    }
     // Bearer required for remaining paths (Ed25519, OAuth)
     if (!headerAuth.startsWith("Bearer ")) {
         logWarn("AuthMissingBearer", req);
-        return sendError(res, 401, "AUTH_REQUIRED", "Missing Bearer token");
+        return sendError(res, 401, "AUTH_REQUIRED", "Missing Bearer token", {
+            hint: "AAuth-signed agents can authenticate without Bearer once an active agent_grant matches their identity. " +
+                "Create a grant via Inspector → Agents → Grants.",
+        });
     }
     const bearerToken = headerAuth.slice("Bearer ".length).trim();
     // Try to validate as Ed25519 bearer token first
@@ -1883,18 +1960,33 @@ app.get("/me", async (req, res) => {
     }
 });
 /**
- * Helper to extract authenticated user_id from request
- * Supports: middleware-set user (e.g. dev-local when encryption off), session token, Ed25519 bearer
+ * Helper to extract authenticated user_id from request.
+ * Supports: middleware-set user (Bearer / OAuth / dev-local / AAuth admission),
+ * session token, Ed25519 bearer.
+ *
+ * Stronger AAuth Admission plan: admitted AAuth callers carry
+ * `req.authenticatedUserId` resolved from the matching `agent_grant`'s
+ * owner. This helper applies the same `user_id` mismatch rules to them
+ * as to OAuth/Bearer — payload-driven user pivots are rejected. The
+ * local-dev override remains available only for the local dev user;
+ * AAuth admission can never resolve to that id, so admitted agents are
+ * structurally locked to their grant owner.
  * @param req - Express request object
  * @param providedUserId - Optional user_id from request body/query
  * @returns Authenticated user_id
  * @throws Error if not authenticated or user_id mismatch
  */
 async function getAuthenticatedUserId(req, providedUserId) {
-    // Use user already set by auth middleware (e.g. dev-local when encryption off and no Bearer)
     const authenticatedUserId = req.authenticatedUserId;
+    const aauthAdmissionForRequest = getAAuthAdmissionFromRequest(req);
     if (authenticatedUserId) {
         if (providedUserId && providedUserId !== authenticatedUserId) {
+            // AAuth admission: never honour payload user_id overrides — the
+            // grant owner is the only valid scope for an admitted agent.
+            // Bearer/OAuth flows fall through to the existing rules below.
+            if (aauthAdmissionForRequest?.admitted) {
+                throw new Error(`user_id parameter (${providedUserId}) does not match admitted AAuth user (${authenticatedUserId}); grants only resolve to their owner`);
+            }
             // When authenticated as local dev user, allow body/query user_id override for CLI tests and dev flows.
             // The sandbox public user is intentionally excluded so public sandbox
             // callers cannot pivot into other users' data by spoofing user_id.
@@ -2912,6 +3004,136 @@ app.get("/agents", async (req, res) => {
         return handleApiError(req, res, error, "Failed to list agents", "DB_QUERY_FAILED", "APIError:agents_list");
     }
 });
+// ============================================================================
+// /agents/grants — Stronger AAuth Admission management surface
+//
+// Ergonomic wrappers over the agent_grant entity store for the Inspector
+// grants page and CLI tooling. The structured-store routes
+// (`store_structured`, `correct`) remain available for agents that hold
+// the bootstrap capability and want to manage grants programmatically.
+// All routes require an authenticated user and operate strictly within
+// that user's scope. Cross-user grant access is rejected at the route
+// layer (not just the UI). See docs/subsystems/agent_attribution_integration.md.
+//
+// REGISTERED BEFORE `/agents/:key` so Express's first-match ordering does
+// not route `/agents/grants` into the observed-agents handler.
+// ============================================================================
+const grantsCommonHandlers = {
+    errorEnvelopeFromGrantError: (err) => {
+        const e = err;
+        if (e && typeof e === "object" && typeof e.code === "string" && typeof e.statusCode === "number") {
+            return {
+                statusCode: e.statusCode,
+                envelope: buildErrorEnvelope(e.code.toUpperCase(), e.message ?? "Grant error", {
+                    code: e.code,
+                }),
+            };
+        }
+        return null;
+    },
+};
+app.get("/agents/grants", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const { listGrantsForUser } = await import("./services/agent_grants.js");
+        const status = typeof req.query.status === "string" ? req.query.status : undefined;
+        const query = typeof req.query.q === "string" ? req.query.q : undefined;
+        const grants = await listGrantsForUser(userId, {
+            status: status || "all",
+            query,
+        });
+        return res.json({ grants });
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to list agent grants", "DB_QUERY_FAILED", "APIError:agents_grants_list");
+    }
+});
+app.get("/agents/grants/:id", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.query.user_id);
+        const { getGrant } = await import("./services/agent_grants.js");
+        const grant = await getGrant(userId, req.params.id);
+        if (!grant) {
+            return sendError(res, 404, "RESOURCE_NOT_FOUND", `Agent grant not found: ${req.params.id}`);
+        }
+        return res.json({ grant });
+    }
+    catch (error) {
+        return handleApiError(req, res, error, "Failed to fetch agent grant", "DB_QUERY_FAILED", "APIError:agents_grants_detail");
+    }
+});
+app.post("/agents/grants", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.body?.user_id ?? undefined);
+        const body = (req.body ?? {});
+        const { createGrant } = await import("./services/agent_grants.js");
+        const grant = await createGrant(userId, {
+            label: typeof body.label === "string" ? body.label : "",
+            capabilities: Array.isArray(body.capabilities) ? body.capabilities : [],
+            status: body.status ?? "active",
+            match_sub: typeof body.match_sub === "string" ? body.match_sub : null,
+            match_iss: typeof body.match_iss === "string" ? body.match_iss : null,
+            match_thumbprint: typeof body.match_thumbprint === "string" ? body.match_thumbprint : null,
+            notes: typeof body.notes === "string" ? body.notes : null,
+        });
+        return res.status(201).json({ grant });
+    }
+    catch (error) {
+        const mapped = grantsCommonHandlers.errorEnvelopeFromGrantError(error);
+        if (mapped) {
+            return res.status(mapped.statusCode).json(mapped.envelope);
+        }
+        return handleApiError(req, res, error, "Failed to create agent grant", "DB_QUERY_FAILED", "APIError:agents_grants_create");
+    }
+});
+app.patch("/agents/grants/:id", async (req, res) => {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.body?.user_id ?? undefined);
+        const body = (req.body ?? {});
+        const { updateGrantFields } = await import("./services/agent_grants.js");
+        const updates = {};
+        if (typeof body.label === "string")
+            updates.label = body.label;
+        if (Array.isArray(body.capabilities))
+            updates.capabilities = body.capabilities;
+        if (body.notes === null || typeof body.notes === "string")
+            updates.notes = body.notes;
+        if (body.match_sub === null || typeof body.match_sub === "string")
+            updates.match_sub = body.match_sub;
+        if (body.match_iss === null || typeof body.match_iss === "string")
+            updates.match_iss = body.match_iss;
+        if (body.match_thumbprint === null || typeof body.match_thumbprint === "string") {
+            updates.match_thumbprint = body.match_thumbprint;
+        }
+        const grant = await updateGrantFields(userId, req.params.id, updates);
+        return res.json({ grant });
+    }
+    catch (error) {
+        const mapped = grantsCommonHandlers.errorEnvelopeFromGrantError(error);
+        if (mapped) {
+            return res.status(mapped.statusCode).json(mapped.envelope);
+        }
+        return handleApiError(req, res, error, "Failed to update agent grant", "DB_QUERY_FAILED", "APIError:agents_grants_update");
+    }
+});
+async function setGrantStatusRoute(req, res, next) {
+    try {
+        const userId = await getAuthenticatedUserId(req, req.body?.user_id ?? undefined);
+        const { setStatus } = await import("./services/agent_grants.js");
+        const grant = await setStatus(userId, req.params.id, next);
+        return res.json({ grant });
+    }
+    catch (error) {
+        const mapped = grantsCommonHandlers.errorEnvelopeFromGrantError(error);
+        if (mapped) {
+            return res.status(mapped.statusCode).json(mapped.envelope);
+        }
+        return handleApiError(req, res, error, `Failed to ${next === "active" ? "restore" : next} agent grant`, "DB_QUERY_FAILED", `APIError:agents_grants_${next}`);
+    }
+}
+app.post("/agents/grants/:id/suspend", (req, res) => setGrantStatusRoute(req, res, "suspended"));
+app.post("/agents/grants/:id/revoke", (req, res) => setGrantStatusRoute(req, res, "revoked"));
+app.post("/agents/grants/:id/restore", (req, res) => setGrantStatusRoute(req, res, "active"));
 // GET /api/agents/:key — One agent's identity + rollup counts
 // REQUIRES AUTHENTICATION
 app.get("/agents/:key", async (req, res) => {
@@ -3482,7 +3704,7 @@ app.post("/observations/create", async (req, res) => {
         return res.status(500).json(buildErrorEnvelope("DB_QUERY_FAILED", message));
     }
 });
-async function storeStructuredForApi(params) {
+export async function storeStructuredForApi(params) {
     const { userId, entities, sourcePriority, observationSource, idempotencyKey, originalFilename, relationships, commit: commitInput, strict: strictInput, } = params;
     const commit = commitInput !== false;
     const strict = strictInput === true;
@@ -3501,6 +3723,21 @@ async function storeStructuredForApi(params) {
             enforceAgentCapability("create_relationship", entityTypes, capabilityCtx);
         }
     }
+    // Protected-entity-types guard: governance state (`agent_grant`, etc.)
+    // is gated by an explicit capability on the admitted grant. Mirrors
+    // the same check made deep in `createObservation` so callers see a
+    // structured `capability_denied` envelope before any writes.
+    {
+        const entityTypes = entities
+            .map((entity) => entity?.entity_type)
+            .filter((t) => typeof t === "string" && t.length > 0);
+        assertCanWriteProtectedBatch({
+            entity_types: entityTypes,
+            op: "store_structured",
+            identity: getCurrentAgentIdentity(),
+            admission: getCurrentAAuthAdmission(),
+        });
+    }
     const { resolveEntityWithTrace, CanonicalNameUnresolvedError, MergeRefusedError } = await import("./services/entity_resolution.js");
     const { detectFlatPackedRows, FlatPackedRowsError } = await import("./services/flat_packed_detection.js");
     // R4: lazy import so the structured-store handler can attach required
@@ -3892,8 +4129,13 @@ async function storeUnstructuredForApi(params) {
         observations_created: 0,
     };
 }
-// POST /api/store - Unified store for structured, unstructured, or combined payloads
-app.post("/store", writeRateLimit, async (req, res) => {
+// Shared handler body for the unified /store endpoint. Extracted so that the
+// sandbox-only POST /sandbox/aauth-only/store route below can reuse the exact
+// same write semantics (validation, auth, structured + unstructured flows,
+// error envelopes) without duplicating logic. Both routes funnel through
+// getAuthenticatedUserId, which honors the α attribution partitioning applied
+// in the sandbox bypass above.
+async function handleStorePost(req, res) {
     const parsed = StoreRequestSchema.safeParse(req.body);
     if (!parsed.success) {
         logWarn("ValidationError:store", req, {
@@ -4009,7 +4251,29 @@ app.post("/store", writeRateLimit, async (req, res) => {
         const message = error instanceof Error ? error.message : "Failed to store payload";
         return sendError(res, 500, "DB_QUERY_FAILED", message);
     }
-});
+}
+// POST /api/store - Unified store for structured, unstructured, or combined payloads
+app.post("/store", writeRateLimit, handleStorePost);
+// γ-write: sandbox-only route that EXPLICITLY requires a verified AAuth
+// signature before delegating to the same handleStorePost handler. Unlike the
+// global /store endpoint (which accepts bearer auth, sandbox public-user
+// fallback, OR AAuth-derived attribution), this route makes AAuth admission
+// the gate: unsigned requests get 401 here. The route is only registered when
+// isSandboxMode() is true, so it does not exist in production. Demo value:
+// shows identity-bound provenance — a write performed by an AAuth-signed
+// agent lands under the per-thumbprint user from α and is round-trippable via
+// /entities/query, /entities/:id, and /stats scoped to that same identity.
+if (isSandboxMode()) {
+    const aauthRequired = (req, res, next) => {
+        const aauthCtx = req.aauth;
+        if (aauthCtx?.verified === true && typeof aauthCtx.thumbprint === "string") {
+            return next();
+        }
+        return sendError(res, 401, "AAUTH_REQUIRED", "POST /sandbox/aauth-only/store requires a verified AAuth signature (RFC 9421 + aa-agent+jwt).");
+    };
+    app.post("/sandbox/aauth-only/store", writeRateLimit, aauthRequired, handleStorePost);
+    logger.info("[Sandbox] AAuth-required write route enabled at POST /sandbox/aauth-only/store");
+}
 // POST /api/store/unstructured - Store raw file (base64), optional AI interpretation
 app.post("/store/unstructured", async (req, res) => {
     const parsed = StoreUnstructuredRequestSchema.safeParse(req.body);
@@ -5002,6 +5266,12 @@ app.post("/correct", async (req, res) => {
         if (correctCtx) {
             enforceAgentCapability("correct", [entity_type], correctCtx);
         }
+        assertCanWriteProtectedBatch({
+            entity_types: [entity_type],
+            op: "correct",
+            identity: getCurrentAgentIdentity(),
+            admission: getCurrentAAuthAdmission(),
+        });
         const { createCorrection } = await import("./services/correction.js");
         const result = await createCorrection({
             entity_id,
@@ -5067,6 +5337,7 @@ app.get("/session", async (req, res) => {
             identity,
             middlewareDecision: getAttributionDecisionFromRequest(req),
             rawClientInfoName: rawClientName,
+            admission: getAAuthAdmissionFromRequest(req),
         });
         return res.json(session);
     }
@@ -5353,7 +5624,16 @@ app.get("/openapi_actions.yaml", (req, res) => {
 function tryListen(port) {
     return new Promise((resolve, reject) => {
         const server = app.listen(port, () => {
-            resolve({ server, port });
+            // When `port === 0` the OS assigns an ephemeral port. We must report
+            // the actually-bound port back to callers (the eval harness's
+            // isolated server fixture writes it to NEOTOMA_SESSION_PORT_FILE so
+            // the test harness can hit /health). Without this, a port file would
+            // contain the literal "0" and the health probe would never connect.
+            const addr = server.address();
+            const boundPort = addr && typeof addr === "object" && typeof addr.port === "number"
+                ? addr.port
+                : port;
+            resolve({ server, port: boundPort });
         });
         server.once("error", (err) => {
             server.close();
@@ -5363,6 +5643,26 @@ function tryListen(port) {
 }
 // Export function to start HTTP server (called explicitly, not on import)
 export async function startHTTPServer() {
+    // Stronger AAuth Admission plan: capabilities now live on agent_grant
+    // entities. If the legacy NEOTOMA_AGENT_CAPABILITIES_* env vars are
+    // still set, fail fast with a structured pointer to the migration
+    // command. See docs/subsystems/agent_attribution_integration.md.
+    const { assertNoLegacyCapabilityEnv, LegacyAgentCapabilityEnvError } = await import("./services/agent_capabilities.js");
+    try {
+        assertNoLegacyCapabilityEnv();
+    }
+    catch (err) {
+        if (err instanceof LegacyAgentCapabilityEnvError) {
+            logger.error(JSON.stringify({
+                event: "boot_failed_legacy_agent_capabilities_env",
+                variables: err.variables,
+                migration_command: err.migrationCommand,
+                message: err.message,
+            }));
+            throw err;
+        }
+        throw err;
+    }
     // Initialize encryption service
     await initServerKeys();
     // Sandbox mode: ensure the `sandbox_abuse_report` entity type is registered
@@ -5383,24 +5683,28 @@ export async function startHTTPServer() {
     const basePort = httpPortEnv ? parseInt(httpPortEnv, 10) : config.httpPort || 3080;
     const portFile = process.env.NEOTOMA_SESSION_PORT_FILE;
     const maxTries = 20;
-    for (let offset = 0; offset < maxTries; offset++) {
+    // basePort === 0 means OS-assigned ephemeral port; retrying on EADDRINUSE
+    // makes no sense (and would try port 1, 2, ...). The eval harness uses
+    // ephemeral ports to avoid colliding with the operator's dev server.
+    const triesLimit = basePort === 0 ? 1 : maxTries;
+    for (let offset = 0; offset < triesLimit; offset++) {
         const port = basePort + offset;
         try {
-            const { server } = await tryListen(port);
+            const { server, port: boundPort } = await tryListen(port);
             if (portFile) {
-                fs.writeFileSync(portFile, String(port), "utf-8");
+                fs.writeFileSync(portFile, String(boundPort), "utf-8");
             }
             // eslint-disable-next-line no-console
-            console.log(`HTTP Actions listening on :${port}`);
+            console.log(`HTTP Actions listening on :${boundPort}`);
             // Start background OAuth state cleanup job
             import("./services/mcp_oauth.js").then((oauth) => {
                 oauth.startStateCleanupJob();
             });
-            return { server, port };
+            return { server, port: boundPort };
         }
         catch (err) {
             const code = err?.code;
-            if (code === "EADDRINUSE" && offset < maxTries - 1) {
+            if (code === "EADDRINUSE" && offset < triesLimit - 1) {
                 continue;
             }
             throw err;