neotoma 0.28.0 → 0.29.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/README.md +3 -1
  2. package/dist/actions.d.ts +2 -0
  3. package/dist/actions.d.ts.map +1 -1
  4. package/dist/actions.js +434 -138
  5. package/dist/actions.js.map +1 -1
  6. package/dist/docs/architecture/idempotence_pattern.md +15 -0
  7. package/dist/docs/developer/cli_agent_instructions.md +5 -0
  8. package/dist/docs/developer/mcp/instructions.md +3 -2
  9. package/dist/docs/developer/subscriptions_guide.md +6 -0
  10. package/dist/docs/operations/configuration.md +4 -2
  11. package/dist/docs/subsystems/errors.md +10 -6
  12. package/dist/docs/subsystems/guest_access_policy.md +11 -0
  13. package/dist/docs/subsystems/substrate_events.md +7 -2
  14. package/dist/docs/testing/automated_test_catalog.md +38 -16
  15. package/dist/events/substrate_store_emit.d.ts +32 -0
  16. package/dist/events/substrate_store_emit.d.ts.map +1 -1
  17. package/dist/events/substrate_store_emit.js +47 -0
  18. package/dist/events/substrate_store_emit.js.map +1 -1
  19. package/dist/events/types.d.ts +6 -0
  20. package/dist/events/types.d.ts.map +1 -1
  21. package/dist/repositories/db/driver.d.ts +38 -3
  22. package/dist/repositories/db/driver.d.ts.map +1 -1
  23. package/dist/repositories/db/driver.js +79 -3
  24. package/dist/repositories/db/driver.js.map +1 -1
  25. package/dist/repositories/libsql/libsql_driver.d.ts +15 -0
  26. package/dist/repositories/libsql/libsql_driver.d.ts.map +1 -1
  27. package/dist/repositories/libsql/libsql_driver.js +15 -0
  28. package/dist/repositories/libsql/libsql_driver.js.map +1 -1
  29. package/dist/repositories/sqlite/sqlite_client.d.ts.map +1 -1
  30. package/dist/repositories/sqlite/sqlite_client.js +69 -0
  31. package/dist/repositories/sqlite/sqlite_client.js.map +1 -1
  32. package/dist/repositories/sqlite/sqlite_driver.d.ts +10 -4
  33. package/dist/repositories/sqlite/sqlite_driver.d.ts.map +1 -1
  34. package/dist/repositories/sqlite/sqlite_driver.js +16 -13
  35. package/dist/repositories/sqlite/sqlite_driver.js.map +1 -1
  36. package/dist/repositories/worker/worker_file_database.d.ts +48 -9
  37. package/dist/repositories/worker/worker_file_database.d.ts.map +1 -1
  38. package/dist/repositories/worker/worker_file_database.js +257 -42
  39. package/dist/repositories/worker/worker_file_database.js.map +1 -1
  40. package/dist/server.d.ts.map +1 -1
  41. package/dist/server.js +76 -45
  42. package/dist/server.js.map +1 -1
  43. package/dist/services/access_policy.d.ts.map +1 -1
  44. package/dist/services/access_policy.js +2 -3
  45. package/dist/services/access_policy.js.map +1 -1
  46. package/dist/services/field_constraints.d.ts +7 -2
  47. package/dist/services/field_constraints.d.ts.map +1 -1
  48. package/dist/services/field_constraints.js +40 -5
  49. package/dist/services/field_constraints.js.map +1 -1
  50. package/dist/services/guest_access_token.d.ts +60 -1
  51. package/dist/services/guest_access_token.d.ts.map +1 -1
  52. package/dist/services/guest_access_token.js +193 -29
  53. package/dist/services/guest_access_token.js.map +1 -1
  54. package/dist/services/interpretation.d.ts.map +1 -1
  55. package/dist/services/interpretation.js +47 -28
  56. package/dist/services/interpretation.js.map +1 -1
  57. package/dist/services/rendered_page/conformance.d.ts.map +1 -1
  58. package/dist/services/rendered_page/conformance.js +31 -10
  59. package/dist/services/rendered_page/conformance.js.map +1 -1
  60. package/dist/services/safe_pattern.d.ts +107 -0
  61. package/dist/services/safe_pattern.d.ts.map +1 -0
  62. package/dist/services/safe_pattern.js +437 -0
  63. package/dist/services/safe_pattern.js.map +1 -0
  64. package/dist/services/schema_derived_entity_extraction.d.ts +8 -1
  65. package/dist/services/schema_derived_entity_extraction.d.ts.map +1 -1
  66. package/dist/services/schema_derived_entity_extraction.js +29 -11
  67. package/dist/services/schema_derived_entity_extraction.js.map +1 -1
  68. package/dist/services/schema_registry.d.ts +6 -3
  69. package/dist/services/schema_registry.d.ts.map +1 -1
  70. package/dist/services/schema_registry.js +41 -7
  71. package/dist/services/schema_registry.js.map +1 -1
  72. package/dist/services/store_conditional.d.ts.map +1 -1
  73. package/dist/services/store_conditional.js +8 -3
  74. package/dist/services/store_conditional.js.map +1 -1
  75. package/dist/services/store_write_state.d.ts +45 -3
  76. package/dist/services/store_write_state.d.ts.map +1 -1
  77. package/dist/services/store_write_state.js +62 -3
  78. package/dist/services/store_write_state.js.map +1 -1
  79. package/dist/shared/contract_mappings.d.ts.map +1 -1
  80. package/dist/shared/contract_mappings.js +7 -0
  81. package/dist/shared/contract_mappings.js.map +1 -1
  82. package/dist/shared/openapi_types.d.ts +149 -48
  83. package/dist/shared/openapi_types.d.ts.map +1 -1
  84. package/dist/tool_definitions.js +1 -1
  85. package/dist/tool_definitions.js.map +1 -1
  86. package/docs/developer/mcp/instructions.md +3 -2
  87. package/openapi.yaml +153 -26
  88. package/package.json +7 -5
package/dist/actions.js CHANGED
@@ -40,7 +40,7 @@ import { StorePolicyDeniedError, StorePolicyUnavailableError } from "./services/
40
40
  import { AgentCapabilityError, contextFromAgentIdentity, enforceAgentCapability, } from "./services/agent_capabilities.js";
41
41
  import { ISSUE_THREAD_ENTITY_TYPES, assertCurrentAgentMay, assertCurrentAgentMayLink, assertCurrentAgentMayOnEntities, assetEntityTypeForMimeType, } from "./services/mutation_capability.js";
42
42
  import { AccessPolicyError } from "./services/access_policy.js";
43
- import { hashGuestAccessToken } from "./services/guest_access_token.js";
43
+ import { GUEST_TOKEN_INVALID_CODE, GUEST_TOKEN_INVALID_MESSAGE, GUEST_TOKEN_SCOPE_CODE, GuestTokenInvalidError, GuestTokenScopeError, checkGuestTokenForEntity, hashGuestAccessToken, validateGuestAccessToken as validateGuestToken, } from "./services/guest_access_token.js";
44
44
  import { subscriptionWithinGuestScope } from "./services/subscriptions/guest_scope.js";
45
45
  import { IssueTransportError, IssueValidationError } from "./services/issues/errors.js";
46
46
  import { externalActorFromCallerInput } from "./services/issues/external_actor_builder.js";
@@ -58,9 +58,11 @@ import { adoptRecoveredSessionId, completeSyntheticMcpHandshake, mintMcpHttpSess
58
58
  import { describeMcpStandardHeadersForLog, headerRejectionJsonRpcBody, jsonRpcIdOf, readClientInfoFromMeta, readRequestMeta, screenMcpStandardHeaders, selectMcpHttpEra, validateModernMcpRequest, } from "./mcp_http_stateless.js";
59
59
  import { NeotomaServer } from "./server.js";
60
60
  import { logger } from "./utils/logger.js";
61
+ import { storeWriteCompletionResponseFields, } from "./services/store_write_state.js";
62
+ import { withPatternBudget, SchemaPatternRefusalError } from "./services/safe_pattern.js";
61
63
  import { formatRequestLogLine } from "./utils/safe_request_log_format.js";
62
64
  import { connectionIdForLog } from "./utils/connection_id_log.js";
63
- import { emitEntitySnapshotChange, emitObservationCreated, shallowFieldsChanged, } from "./events/substrate_store_emit.js";
65
+ import { emitStoreWriteEvents } from "./events/substrate_store_emit.js";
64
66
  import { OAuthError } from "./services/mcp_oauth_errors.js";
65
67
  import { ensureLocalDevUser, ensureLocalSandboxUser, ensureSandboxAauthUser, ensureSandboxPublicUser, LOCAL_DEV_USER_ID, SANDBOX_PUBLIC_USER_ID, } from "./services/local_auth.js";
66
68
  import { buildSandboxBootBannerLines, decidePostureReconciliation, extractBoundHost, isSandboxMode, resolveForceMode, resolveRefusePolicy, resolveSandboxMode, sandboxDestructiveGuard, sandboxHeaderMiddleware, } from "./services/sandbox_mode.js";
@@ -3368,15 +3370,62 @@ export function routeAcceptsGuestPrincipal(req) {
3368
3370
  if (req.method === "GET") {
3369
3371
  if (path === "/events/stream")
3370
3372
  return true;
3371
- const match = /^\/entities\/([^/]+)(?:\/(?:observations|relationships|html))?$/.exec(path);
3372
- if (!match)
3373
- return false;
3374
- // Fail closed: a reserved static segment is a route, not an entity id, so it
3375
- // is not guest-eligible unless it is explicitly listed as such above.
3376
- return !RESERVED_ENTITY_PATH_SEGMENTS.has(match[1]);
3373
+ return routeIsEntityDetailRead(req);
3377
3374
  }
3378
3375
  return false;
3379
3376
  }
3377
+ /**
3378
+ * GET /entities/:id and its /observations, /relationships and /html reads: the
3379
+ * guest-capable routes that read one entity.
3380
+ */
3381
+ function routeIsEntityDetailRead(req) {
3382
+ if (req.method !== "GET")
3383
+ return false;
3384
+ const match = /^\/entities\/([^/]+)(?:\/(?:observations|relationships|html))?$/.exec(req.path);
3385
+ if (!match)
3386
+ return false;
3387
+ // Fail closed: a reserved static segment is a route, not an entity id, so it
3388
+ // is not guest-eligible unless it is explicitly listed as such above.
3389
+ return !RESERVED_ENTITY_PATH_SEGMENTS.has(match[1]);
3390
+ }
3391
+ /**
3392
+ * Stronger AAuth Admission: when the request carries a verified AAuth identity
3393
+ * that the admission middleware resolved to an active `agent_grant`, stamp the
3394
+ * grant owner as the user principal. The admission middleware has already set
3395
+ * `req.authenticatedUserId`; it must still match, so a later auth step that
3396
+ * replaced it is never overridden here.
3397
+ */
3398
+ function stampAdmittedAAuthPrincipal(req) {
3399
+ const admission = getAAuthAdmissionFromRequest(req);
3400
+ if (!admission?.admitted ||
3401
+ !admission.user_id ||
3402
+ req.authenticatedUserId !== admission.user_id) {
3403
+ return false;
3404
+ }
3405
+ stampUserPrincipal(req, admission.user_id);
3406
+ logger.info(`[Auth] ${req.method} ${req.path} auth_method=aauth_admitted user_id=${admission.user_id} grant_id=${admission.grant_id ?? "?"}`);
3407
+ return true;
3408
+ }
3409
+ /**
3410
+ * An admitted agent reading an entity with no guest token reads as its grant
3411
+ * owner, the same as on POST /entities/query, and not as a guest. Without this
3412
+ * the no-Bearer branches stamp it as a guest first (it is signed, so it has a
3413
+ * thumbprint), and the entity type's guest access policy then refuses it.
3414
+ *
3415
+ * A request that presents a guest token (as `access_token` or as a Bearer) is
3416
+ * left to the guest path and judged by that token. Issue, subscription and
3417
+ * event-stream routes are not entity reads and keep their guest handling.
3418
+ * Sandbox mode keeps its own per-thumbprint attribution.
3419
+ */
3420
+ function maybeStampAdmittedEntityReader(req) {
3421
+ if (!routeIsEntityDetailRead(req))
3422
+ return false;
3423
+ if (isSandboxMode())
3424
+ return false;
3425
+ if (guestAccessTokenFromRequest(req))
3426
+ return false;
3427
+ return stampAdmittedAAuthPrincipal(req);
3428
+ }
3380
3429
  /**
3381
3430
  * Exported for unit tests: the two issue-write routes that extend local-loopback
3382
3431
  * trust to unauthenticated requests. A local request to `/issues/submit` or
@@ -3489,13 +3538,9 @@ async function maybeStampGuestPrincipal(req) {
3489
3538
  stampGuestPrincipal(req, buildAnonymousGuestPrincipal());
3490
3539
  return true;
3491
3540
  }
3492
- const headerAuth = (req.headers.authorization || req.headers.Authorization || "");
3493
- if (headerAuth.startsWith("Bearer ") && guestPrincipal.accessToken) {
3494
- const { validateGuestAccessToken } = await import("./services/guest_access_token.js");
3495
- if (!(await validateGuestAccessToken(guestPrincipal.accessToken))) {
3496
- return false;
3497
- }
3498
- }
3541
+ // The presented token is validated by the route's guest resolver, which
3542
+ // answers an invalid token with 401 GUEST_TOKEN_INVALID whether it arrived
3543
+ // as `access_token` or as `Authorization: Bearer`.
3499
3544
  stampGuestPrincipal(req, guestPrincipal);
3500
3545
  return true;
3501
3546
  }
@@ -3567,7 +3612,11 @@ export async function resolveGuestUserId(req, principal) {
3567
3612
  if (authenticatedUserId)
3568
3613
  return authenticatedUserId;
3569
3614
  if (principal.guestId.accessToken) {
3570
- const { hashGuestAccessToken } = await import("./services/guest_access_token.js");
3615
+ // A presented token must pass the shared validity check (known, unexpired,
3616
+ // unrevoked) before it maps to an owner.
3617
+ if (!(await principalGuestGrant(principal))) {
3618
+ throw new GuestTokenInvalidError();
3619
+ }
3571
3620
  const tokenHash = hashGuestAccessToken(principal.guestId.accessToken);
3572
3621
  const tokenEntityId = `guest_token_${tokenHash.slice(0, 16)}`;
3573
3622
  const { data: tokenEntity } = await db
@@ -3623,17 +3672,16 @@ async function resolveGuestSubscriptionScope(req, principal) {
3623
3672
  return { userId: authenticatedUserId, entityIds: null };
3624
3673
  }
3625
3674
  if (principal.guestId.accessToken) {
3626
- const { validateGuestAccessToken } = await import("./services/guest_access_token.js");
3627
- const tokenGrant = await validateGuestAccessToken(principal.guestId.accessToken);
3675
+ const tokenGrant = await principalGuestGrant(principal);
3628
3676
  if (!tokenGrant) {
3629
- throw new Error("Not authenticated - invalid guest access token");
3677
+ throw new GuestTokenInvalidError();
3630
3678
  }
3631
3679
  const userId = await resolveGuestUserId(req, principal);
3632
3680
  if (!userId) {
3633
3681
  throw new Error("Not authenticated - guest access token did not resolve an owner");
3634
3682
  }
3635
3683
  if (!tokenGrant.entity_ids.length) {
3636
- throw new Error("Guest access token grants no entity scope; subscription and event routes require a token minted with entity_ids");
3684
+ throw new GuestTokenScopeError();
3637
3685
  }
3638
3686
  return { userId, entityIds: tokenGrant.entity_ids };
3639
3687
  }
@@ -3647,26 +3695,58 @@ async function resolveGuestSubscriptionScope(req, principal) {
3647
3695
  }
3648
3696
  throw new Error("Not authenticated - guest principal cannot resolve a subscription scope: no valid token grant and not a local request");
3649
3697
  }
3650
- async function assertValidGuestAccessToken(principal) {
3698
+ /** A principal's token is validated once per request; the result is shared. */
3699
+ const principalGrantCache = new WeakMap();
3700
+ function principalGuestGrant(principal) {
3651
3701
  const accessToken = principal.guestId.accessToken;
3652
3702
  if (!accessToken)
3703
+ return Promise.resolve(null);
3704
+ let cached = principalGrantCache.get(principal);
3705
+ if (!cached) {
3706
+ cached = validateGuestToken(accessToken);
3707
+ principalGrantCache.set(principal, cached);
3708
+ // Do not keep a failed read: the next call reads again.
3709
+ cached.catch(() => principalGrantCache.delete(principal));
3710
+ }
3711
+ return cached;
3712
+ }
3713
+ async function assertValidGuestAccessToken(principal) {
3714
+ if (!principal.guestId.accessToken)
3653
3715
  return;
3654
- const { validateGuestAccessToken } = await import("./services/guest_access_token.js");
3655
- const tokenGrant = await validateGuestAccessToken(accessToken);
3656
- if (!tokenGrant) {
3657
- throw new Error("Not authenticated - invalid guest access token");
3716
+ if (!(await principalGuestGrant(principal))) {
3717
+ throw new GuestTokenInvalidError();
3658
3718
  }
3659
3719
  }
3660
- async function resolveGuestScopedEntityAccess(principal, entityId, expectedEntityType) {
3720
+ /**
3721
+ * Guest access governed ONLY by the type-level access policy (plus the
3722
+ * submitter-scoped token/thumbprint rules). Used by every guest write route and
3723
+ * by every guest read route that is not a share-link route. Never consults the
3724
+ * entity-scoped precedence in resolveGuestShareLinkEntityAccess.
3725
+ */
3726
+ async function resolveGuestPolicyGovernedEntityAccess(principal, entityId, expectedEntityType) {
3661
3727
  await assertValidGuestAccessToken(principal);
3728
+ const accessToken = principal.guestId.accessToken;
3729
+ const tokenOnly = Boolean(accessToken && !principal.guestId.thumbprint);
3662
3730
  const { data: entity, error: entityError } = await db
3663
3731
  .from("entities")
3664
3732
  .select("id, entity_type, user_id")
3665
3733
  .eq("id", entityId)
3666
3734
  .single();
3667
3735
  if (entityError || !entity || (expectedEntityType && entity.entity_type !== expectedEntityType)) {
3736
+ // A token-only caller gets the same answer for an unknown item as for an
3737
+ // item its token does not name.
3738
+ if (tokenOnly)
3739
+ throw new GuestTokenScopeError();
3668
3740
  throw new Error(expectedEntityType === "issue" ? "Issue entity not found." : "Entity not found.");
3669
3741
  }
3742
+ // A guest token is a grant for the entities it covers and for nothing else,
3743
+ // under every policy mode. A caller holding only a token must present one
3744
+ // that covers this entity; a signed agent identity is judged separately.
3745
+ const tokenCovers = accessToken !== undefined &&
3746
+ (await checkGuestTokenForEntity(accessToken, entityId, entity, await principalGuestGrant(principal))).state === "granted";
3747
+ if (tokenOnly && !tokenCovers) {
3748
+ throw new GuestTokenScopeError();
3749
+ }
3670
3750
  const { resolveGuestReadAccess } = await import("./services/access_policy.js");
3671
3751
  const decision = await resolveGuestReadAccess(entity.entity_type, principal.guestId);
3672
3752
  if (!decision.allowed) {
@@ -3677,46 +3757,12 @@ async function resolveGuestScopedEntityAccess(principal, entityId, expectedEntit
3677
3757
  reason: decision.reason,
3678
3758
  });
3679
3759
  }
3760
+ if (tokenOnly) {
3761
+ return { userId: entity.user_id, entityType: entity.entity_type };
3762
+ }
3680
3763
  if (decision.scopeFilter === "submitter_only") {
3681
- if (principal.guestId.accessToken) {
3682
- const { tokenGrantsAccessTo, hashGuestAccessToken } = await import("./services/guest_access_token.js");
3683
- if (await tokenGrantsAccessTo(principal.guestId.accessToken, entityId)) {
3684
- return { userId: entity.user_id, entityType: entity.entity_type };
3685
- }
3686
- if (entity.entity_type === "issue") {
3687
- const tokenHash = hashGuestAccessToken(principal.guestId.accessToken);
3688
- // Only the entity owner's own rows count as submitter evidence.
3689
- const { data: issueObservations } = await db
3690
- .from("observations")
3691
- .select("fields")
3692
- .eq("entity_id", entityId)
3693
- .eq("user_id", entity.user_id);
3694
- for (const observation of issueObservations ?? []) {
3695
- const rawFields = observation.fields;
3696
- const fields = typeof rawFields === "string"
3697
- ? JSON.parse(rawFields)
3698
- : rawFields && typeof rawFields === "object"
3699
- ? rawFields
3700
- : undefined;
3701
- if (fields
3702
- ?.guest_access_token_hash === tokenHash) {
3703
- return { userId: entity.user_id, entityType: entity.entity_type };
3704
- }
3705
- }
3706
- const { data: issueRelationships } = await db
3707
- .from("relationship_snapshots")
3708
- .select("target_entity_id")
3709
- .eq("source_entity_id", entityId)
3710
- .eq("relationship_type", "REFERS_TO")
3711
- .eq("user_id", entity.user_id);
3712
- for (const relationship of issueRelationships ?? []) {
3713
- const conversationId = relationship.target_entity_id;
3714
- if (conversationId &&
3715
- (await tokenGrantsAccessTo(principal.guestId.accessToken, conversationId))) {
3716
- return { userId: entity.user_id, entityType: entity.entity_type };
3717
- }
3718
- }
3719
- }
3764
+ if (tokenCovers) {
3765
+ return { userId: entity.user_id, entityType: entity.entity_type };
3720
3766
  }
3721
3767
  const { data: observations } = await db
3722
3768
  .from("observations")
@@ -3737,6 +3783,173 @@ async function resolveGuestScopedEntityAccess(principal, entityId, expectedEntit
3737
3783
  }
3738
3784
  return { userId: entity.user_id, entityType: entity.entity_type };
3739
3785
  }
3786
+ /**
3787
+ * Guest READ access for the two share-link routes only: GET /entities/:id/html
3788
+ * and GET /entities/:id. A valid, unexpired, unrevoked guest token that names
3789
+ * exactly this entity id grants access to that entity before the type policy is
3790
+ * consulted. A merged entity is not served through a token (the redirect would
3791
+ * return a different entity's content), and the caller must re-check deletion
3792
+ * and identity on the loaded entity. Every other case falls through to the
3793
+ * policy-governed resolver unchanged. Not for writes and not for other routes.
3794
+ */
3795
+ async function resolveGuestShareLinkEntityAccess(principal, entityId) {
3796
+ await assertValidGuestAccessToken(principal);
3797
+ const token = principal.guestId.accessToken;
3798
+ if (token) {
3799
+ // Share links are granted only by a token that NAMES the entity; the
3800
+ // issue-submitter rule applies through the policy-governed resolver only.
3801
+ const check = await checkGuestTokenForEntity(token, entityId, undefined, await principalGuestGrant(principal));
3802
+ if (check.state === "granted" && check.reason === "named") {
3803
+ const { data: entity } = await db
3804
+ .from("entities")
3805
+ .select("id, entity_type, user_id, merged_to_entity_id")
3806
+ .eq("id", entityId)
3807
+ .single();
3808
+ if (!entity || entity.merged_to_entity_id)
3809
+ return { kind: "not_found" };
3810
+ return {
3811
+ kind: "found",
3812
+ userId: entity.user_id,
3813
+ entityType: entity.entity_type,
3814
+ viaToken: true,
3815
+ };
3816
+ }
3817
+ }
3818
+ const access = await resolveGuestPolicyGovernedEntityAccess(principal, entityId);
3819
+ return { kind: "found", ...access, viaToken: false };
3820
+ }
3821
+ /**
3822
+ * Whether an entity is currently deleted, decided the same way as the entity
3823
+ * detail and HTML routes (see `getEntityWithProvenance`).
3824
+ */
3825
+ async function entityIsHiddenNow(entity) {
3826
+ const { isEntityHiddenNow } = await import("./services/current_state_reads.js");
3827
+ const hidden = await isEntityHiddenNow(entity);
3828
+ if (hidden !== undefined)
3829
+ return hidden;
3830
+ const { isEntityDeleted } = await import("./services/deletion.js");
3831
+ return isEntityDeleted(entity.id, entity.user_id);
3832
+ }
3833
+ /**
3834
+ * Guest READ access for GET /entities/:id/observations and
3835
+ * GET /entities/:id/relationships. Access is decided by the policy-governed
3836
+ * resolver; a deleted entity then answers `not_found`, as the entity detail and
3837
+ * HTML routes do. When the caller's token covers the entity, deletion is
3838
+ * reported before the type policy, matching the share-link routes; otherwise it
3839
+ * is reported only after access is granted, so an entity the caller may not
3840
+ * read never answers differently for being deleted.
3841
+ */
3842
+ async function resolveGuestEntityReadAccess(principal, entityId) {
3843
+ await assertValidGuestAccessToken(principal);
3844
+ const token = principal.guestId.accessToken;
3845
+ if (token) {
3846
+ const { data: entity } = await db
3847
+ .from("entities")
3848
+ .select("id, entity_type, user_id")
3849
+ .eq("id", entityId)
3850
+ .maybeSingle();
3851
+ const row = entity;
3852
+ if (row) {
3853
+ const check = await checkGuestTokenForEntity(token, entityId, row, await principalGuestGrant(principal));
3854
+ if (check.state === "granted" && (await entityIsHiddenNow(row))) {
3855
+ return { kind: "not_found" };
3856
+ }
3857
+ }
3858
+ }
3859
+ const access = await resolveGuestPolicyGovernedEntityAccess(principal, entityId);
3860
+ if (await entityIsHiddenNow({
3861
+ id: entityId,
3862
+ user_id: access.userId,
3863
+ entity_type: access.entityType,
3864
+ })) {
3865
+ return { kind: "not_found" };
3866
+ }
3867
+ return { kind: "found", ...access };
3868
+ }
3869
+ /** Upper bound on related entities evaluated for one guest expansion request. */
3870
+ export const GUEST_EXPANSION_MAX_RELATED_ENTITIES = 50;
3871
+ /**
3872
+ * The single read decision for one entity and one guest caller, used by
3873
+ * GET /entities/:id, GET /entities/:id/html and related-entity expansion, so
3874
+ * they cannot differ. Access is resolved by `resolveGuestShareLinkEntityAccess`
3875
+ * (a token that names the entity, otherwise the type policy with the
3876
+ * submitter-scoped rules); a deleted or merged entity is `not_found` for every
3877
+ * caller. Whatever it returns as `readable` has `entity_id` equal to the
3878
+ * requested id. A refusal is returned with the error the route answers with,
3879
+ * never thrown, so a caller can decide per entity.
3880
+ */
3881
+ async function decideGuestEntityDetailRead(principal, entityId) {
3882
+ let access;
3883
+ try {
3884
+ access = await resolveGuestShareLinkEntityAccess(principal, entityId);
3885
+ }
3886
+ catch (error) {
3887
+ if (error instanceof GuestTokenInvalidError ||
3888
+ error instanceof GuestTokenScopeError ||
3889
+ error instanceof AccessPolicyError) {
3890
+ return { kind: "refused", error };
3891
+ }
3892
+ throw error;
3893
+ }
3894
+ if (access.kind === "not_found")
3895
+ return { kind: "not_found" };
3896
+ // A merged entity is answered as absent for every guest caller: the decision
3897
+ // is about the requested entity only, so a merge redirect is never followed.
3898
+ const { data: row, error: rowError } = await db
3899
+ .from("entities")
3900
+ .select("id, merged_to_entity_id")
3901
+ .eq("id", entityId)
3902
+ .eq("user_id", access.userId)
3903
+ .maybeSingle();
3904
+ if (rowError)
3905
+ throw rowError;
3906
+ if (!row || row.merged_to_entity_id) {
3907
+ return { kind: "not_found" };
3908
+ }
3909
+ const { getEntityWithProvenance } = await import("./services/entity_queries.js");
3910
+ const entity = await getEntityWithProvenance(entityId, false, access.userId);
3911
+ if (!entity)
3912
+ return { kind: "not_found" };
3913
+ // Invariant: whatever this decision returns as readable is the requested
3914
+ // entity, never another one.
3915
+ if (entity.entity_id !== entityId)
3916
+ return { kind: "not_found" };
3917
+ return { kind: "readable", entity };
3918
+ }
3919
+ /**
3920
+ * The related entities a guest caller may see expanded: exactly those for which
3921
+ * `decideGuestEntityDetailRead` answers `readable` with that same entity, owned
3922
+ * by the owner whose graph is being read. Applies to every guest caller (token
3923
+ * only, token with a signed identity, signed identity only). Every other
3924
+ * related entity keeps its relationship row but is not expanded.
3925
+ *
3926
+ * At most `GUEST_EXPANSION_MAX_RELATED_ENTITIES` related entities are evaluated
3927
+ * per request, in ascending id order; any beyond that bound are not expanded.
3928
+ */
3929
+ async function relatedEntitiesReadableByGuest(principal, ownerId, relatedIds) {
3930
+ const readable = new Set();
3931
+ if (relatedIds.length === 0)
3932
+ return readable;
3933
+ // Only entities that exist in the owner's graph are considered.
3934
+ const { data: rows, error } = await db
3935
+ .from("entities")
3936
+ .select("id")
3937
+ .in("id", relatedIds)
3938
+ .eq("user_id", ownerId);
3939
+ if (error)
3940
+ throw error;
3941
+ const candidates = (rows ?? [])
3942
+ .map((row) => row.id)
3943
+ .sort()
3944
+ .slice(0, GUEST_EXPANSION_MAX_RELATED_ENTITIES);
3945
+ for (const id of candidates) {
3946
+ const decision = await decideGuestEntityDetailRead(principal, id);
3947
+ if (decision.kind === "readable" && decision.entity.entity_id === id) {
3948
+ readable.add(id);
3949
+ }
3950
+ }
3951
+ return readable;
3952
+ }
3740
3953
  // Inspector SPA shell — early content-negotiation handler. Registered BEFORE
3741
3954
  // the auth gate and the JSON data routes (/sources, /entities/:id, /schemas, …)
3742
3955
  // so that a browser navigating to a SPA client route (Accept: text/html) gets
@@ -3770,6 +3983,8 @@ app.use(async (req, res, next) => {
3770
3983
  if (config.storageBackend === "local" &&
3771
3984
  isLocalRequest(req) &&
3772
3985
  !headerAuth.startsWith("Bearer ")) {
3986
+ if (maybeStampAdmittedEntityReader(req))
3987
+ return next();
3773
3988
  if (await maybeStampGuestPrincipal(req)) {
3774
3989
  logger.info(`[Auth] ${req.method} ${req.path} auth_method=guest_capability`);
3775
3990
  return next();
@@ -3839,6 +4054,8 @@ app.use(async (req, res, next) => {
3839
4054
  }
3840
4055
  else {
3841
4056
  if (!headerAuth.startsWith("Bearer ")) {
4057
+ if (maybeStampAdmittedEntityReader(req))
4058
+ return next();
3842
4059
  if (await maybeStampGuestPrincipal(req)) {
3843
4060
  logger.info(`[Auth] ${req.method} ${req.path} auth_method=guest_capability`);
3844
4061
  return next();
@@ -3885,14 +4102,8 @@ app.use(async (req, res, next) => {
3885
4102
  // Bearer is present so agents holding an active grant can reach
3886
4103
  // direct write routes (`/store`, `/observations/create`,
3887
4104
  // `/create_relationship`, `/correct`) without OAuth/Bearer.
3888
- const admissionForRequest = getAAuthAdmissionFromRequest(req);
3889
- if (admissionForRequest?.admitted &&
3890
- admissionForRequest.user_id &&
3891
- req.authenticatedUserId === admissionForRequest.user_id) {
3892
- stampUserPrincipal(req, admissionForRequest.user_id);
3893
- logger.info(`[Auth] ${req.method} ${req.path} auth_method=aauth_admitted user_id=${admissionForRequest.user_id} grant_id=${admissionForRequest.grant_id ?? "?"}`);
4105
+ if (stampAdmittedAAuthPrincipal(req))
3894
4106
  return next();
3895
- }
3896
4107
  // Bearer required for remaining paths (Ed25519, OAuth)
3897
4108
  if (!headerAuth.startsWith("Bearer ")) {
3898
4109
  if (await maybeStampGuestPrincipal(req)) {
@@ -3900,6 +4111,10 @@ app.use(async (req, res, next) => {
3900
4111
  return next();
3901
4112
  }
3902
4113
  logWarn("AuthMissingBearer", req);
4114
+ if (explicitGuestAccessTokenFromRequest(req)) {
4115
+ // A guest token was presented on a route that does not accept it.
4116
+ return sendError(res, 401, GUEST_TOKEN_INVALID_CODE, GUEST_TOKEN_INVALID_MESSAGE);
4117
+ }
3903
4118
  // Plan ent_b4958d038bd41e8694fe0aef Phase 5: surface sandbox availability
3904
4119
  // in the 401 envelope so UIs can replace the hard "Missing Bearer token"
3905
4120
  // error with a sandbox-session onboarding affordance when one is live.
@@ -4160,6 +4375,12 @@ function isGrantPinConflict(error) {
4160
4375
  return (error instanceof Error && error.code === "agent_grant_pin_conflict");
4161
4376
  }
4162
4377
  function handleApiError(req, res, error, defaultMessage, errorCode = "DB_QUERY_FAILED", logContext) {
4378
+ if (error instanceof GuestTokenInvalidError) {
4379
+ return sendError(res, 401, GUEST_TOKEN_INVALID_CODE, GUEST_TOKEN_INVALID_MESSAGE);
4380
+ }
4381
+ if (error instanceof GuestTokenScopeError) {
4382
+ return sendError(res, 403, GUEST_TOKEN_SCOPE_CODE, error.message);
4383
+ }
4163
4384
  if (error instanceof Error && error.message.includes("Not authenticated")) {
4164
4385
  return res.status(401).json(buildErrorEnvelope("AUTH_REQUIRED", "Authentication required.", {
4165
4386
  detail: error.message,
@@ -4521,22 +4742,27 @@ app.get("/entities/:id", async (req, res) => {
4521
4742
  const entityId = req.params.id;
4522
4743
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
4523
4744
  if (principal.kind === "guest") {
4524
- await resolveGuestScopedEntityAccess(principal, entityId);
4525
- }
4526
- else {
4527
- const userId = await getAuthenticatedUserId(req, req.query.user_id);
4528
- const { data: entity, error: entityError } = await db
4529
- .from("entities")
4530
- .select("id, user_id")
4531
- .eq("id", entityId)
4532
- .eq("user_id", userId) // SECURITY: Only return if belongs to authenticated user
4533
- .single();
4534
- if (entityError || !entity) {
4745
+ // The same per-entity decision related-entity expansion uses.
4746
+ const decision = await decideGuestEntityDetailRead(principal, entityId);
4747
+ if (decision.kind === "refused")
4748
+ throw decision.error;
4749
+ if (decision.kind === "not_found") {
4535
4750
  return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4536
4751
  }
4752
+ return res.json(decision.entity);
4753
+ }
4754
+ const userId = await getAuthenticatedUserId(req, req.query.user_id);
4755
+ const { data: entity, error: entityError } = await db
4756
+ .from("entities")
4757
+ .select("id, user_id")
4758
+ .eq("id", entityId)
4759
+ .eq("user_id", userId) // SECURITY: Only return if belongs to authenticated user
4760
+ .single();
4761
+ if (entityError || !entity) {
4762
+ return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4537
4763
  }
4538
4764
  const { getEntityWithProvenance } = await import("./services/entity_queries.js");
4539
- const entityWithProvenance = await getEntityWithProvenance(entityId);
4765
+ const entityWithProvenance = await getEntityWithProvenance(entityId, false);
4540
4766
  if (!entityWithProvenance) {
4541
4767
  return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4542
4768
  }
@@ -4604,9 +4830,7 @@ app.get("/entities/:id/markdown", async (req, res) => {
4604
4830
  if (error instanceof Error && error.message.includes("Not authenticated")) {
4605
4831
  return sendError(res, 401, "AUTH_REQUIRED", error.message);
4606
4832
  }
4607
- logError("APIError:entity_markdown", req, error);
4608
- const message = error instanceof Error ? error.message : "Failed to render entity markdown";
4609
- return sendError(res, 500, "DB_QUERY_FAILED", message);
4833
+ return handleApiError(req, res, error, "Failed to render entity markdown", "DB_QUERY_FAILED", "APIError:entity_markdown");
4610
4834
  }
4611
4835
  });
4612
4836
  // GET /entities/:id/html - Render a `rendered_page` entity as a standalone HTML
@@ -4617,8 +4841,13 @@ app.get("/entities/:id/html", async (req, res) => {
4617
4841
  try {
4618
4842
  const entityId = req.params.id;
4619
4843
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
4844
+ let current;
4620
4845
  if (principal.kind === "guest") {
4621
- await resolveGuestScopedEntityAccess(principal, entityId);
4846
+ // The same per-entity decision as GET /entities/:id.
4847
+ const decision = await decideGuestEntityDetailRead(principal, entityId);
4848
+ if (decision.kind === "refused")
4849
+ throw decision.error;
4850
+ current = decision.kind === "readable" ? decision.entity : null;
4622
4851
  }
4623
4852
  else {
4624
4853
  const userId = await getAuthenticatedUserId(req, req.query.user_id);
@@ -4631,9 +4860,9 @@ app.get("/entities/:id/html", async (req, res) => {
4631
4860
  if (entityError || !entity) {
4632
4861
  return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4633
4862
  }
4863
+ const { getEntityWithProvenance } = await import("./services/entity_queries.js");
4864
+ current = await getEntityWithProvenance(entityId, false);
4634
4865
  }
4635
- const { getEntityWithProvenance } = await import("./services/entity_queries.js");
4636
- const current = await getEntityWithProvenance(entityId);
4637
4866
  if (!current) {
4638
4867
  return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4639
4868
  }
@@ -4661,15 +4890,16 @@ app.get("/entities/:id/html", async (req, res) => {
4661
4890
  return res.send(html);
4662
4891
  }
4663
4892
  catch (error) {
4893
+ if (error instanceof GuestTokenInvalidError || error instanceof GuestTokenScopeError) {
4894
+ return handleApiError(req, res, error, "Failed to render entity HTML");
4895
+ }
4664
4896
  if (error instanceof Error && error.message.includes("Not authenticated")) {
4665
4897
  return sendError(res, 401, "AUTH_REQUIRED", "Missing Bearer token", {
4666
4898
  hint: "AAuth-signed agents can authenticate without Bearer once an active agent_grant matches their identity. Create a grant via Inspector → Agents → Grants.",
4667
4899
  sandbox: { available: false },
4668
4900
  });
4669
4901
  }
4670
- logError("APIError:entity_html", req, error);
4671
- const message = error instanceof Error ? error.message : "Failed to render entity HTML";
4672
- return sendError(res, 500, "DB_QUERY_FAILED", message);
4902
+ return handleApiError(req, res, error, "Failed to render entity HTML", "DB_QUERY_FAILED", "APIError:entity_html");
4673
4903
  }
4674
4904
  });
4675
4905
  // POST /entities/:id/batch_correct - Atomic multi-field correction (Phase 4).
@@ -4731,7 +4961,11 @@ app.get("/entities/:id/observations", async (req, res) => {
4731
4961
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
4732
4962
  let userId;
4733
4963
  if (principal.kind === "guest") {
4734
- userId = (await resolveGuestScopedEntityAccess(principal, entityId)).userId;
4964
+ const access = await resolveGuestEntityReadAccess(principal, entityId);
4965
+ if (access.kind === "not_found") {
4966
+ return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
4967
+ }
4968
+ userId = access.userId;
4735
4969
  }
4736
4970
  else {
4737
4971
  userId = await getAuthenticatedUserId(req, req.query.user_id);
@@ -4778,7 +5012,11 @@ app.get("/entities/:id/relationships", async (req, res) => {
4778
5012
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
4779
5013
  let userId;
4780
5014
  if (principal.kind === "guest") {
4781
- userId = (await resolveGuestScopedEntityAccess(principal, entityId)).userId;
5015
+ const access = await resolveGuestEntityReadAccess(principal, entityId);
5016
+ if (access.kind === "not_found") {
5017
+ return sendError(res, 404, "RESOURCE_NOT_FOUND", "Entity not found");
5018
+ }
5019
+ userId = access.userId;
4782
5020
  }
4783
5021
  else {
4784
5022
  userId = await getAuthenticatedUserId(req, req.query.user_id);
@@ -4827,14 +5065,31 @@ app.get("/entities/:id/relationships", async (req, res) => {
4827
5065
  }
4828
5066
  if (relatedIds.size > 0) {
4829
5067
  const idsArr = Array.from(relatedIds);
4830
- const [snapshotsResult, entitiesResult] = await Promise.all([
4831
- db.from("entity_snapshots").select("*").in("entity_id", idsArr).eq("user_id", userId),
4832
- db
4833
- .from("entities")
4834
- .select("id, canonical_name, entity_type")
4835
- .in("id", idsArr)
4836
- .eq("user_id", userId),
4837
- ]);
5068
+ // A guest caller sees expanded content only for related entities it
5069
+ // could read through GET /entities/:id. The others keep their
5070
+ // relationship rows and an entry with no name, type or snapshot.
5071
+ let expandIds = idsArr;
5072
+ if (principal.kind === "guest") {
5073
+ const readable = await relatedEntitiesReadableByGuest(principal, userId, idsArr);
5074
+ expandIds = idsArr.filter((id) => readable.has(id));
5075
+ }
5076
+ const [snapshotsResult, entitiesResult] = expandIds.length > 0
5077
+ ? await Promise.all([
5078
+ db
5079
+ .from("entity_snapshots")
5080
+ .select("*")
5081
+ .in("entity_id", expandIds)
5082
+ .eq("user_id", userId),
5083
+ db
5084
+ .from("entities")
5085
+ .select("id, canonical_name, entity_type")
5086
+ .in("id", expandIds)
5087
+ .eq("user_id", userId),
5088
+ ])
5089
+ : [
5090
+ { data: [], error: null },
5091
+ { data: [], error: null },
5092
+ ];
4838
5093
  // Merge snapshot + entity rows so callers always get canonical_name
4839
5094
  // and entity_type even when the snapshot row is missing.
4840
5095
  const canonicalNames = new Map();
@@ -6497,11 +6752,13 @@ async function completeInterpretationRun(params) {
6497
6752
  * own atomic transaction, so both run as before.
6498
6753
  */
6499
6754
  export async function storeStructuredForApi(params) {
6755
+ // One pattern-evaluation budget per store request.
6756
+ const run = () => withPatternBudget(() => storeStructuredForApiUnguarded(params));
6500
6757
  if (params.commit === false || params.expectedEntityAbsent === true) {
6501
- return storeStructuredForApiUnguarded(params);
6758
+ return run();
6502
6759
  }
6503
6760
  const { runKeyedStoreWrite } = await import("./services/store_write_state.js");
6504
- return runKeyedStoreWrite(params.userId, params.idempotencyKey, () => storeStructuredForApiUnguarded(params));
6761
+ return runKeyedStoreWrite(params.userId, params.idempotencyKey, run);
6505
6762
  }
6506
6763
  async function storeStructuredForApiUnguarded(params) {
6507
6764
  const { userId, entities, sourcePriority, observationSource, sourcePeerId, idempotencyKey, originalFilename, relationships, interpretation, interpretationSourceId, commit: commitInput, strict: strictInput, dataOrigins, } = params;
@@ -7025,7 +7282,7 @@ async function storeStructuredForApiUnguarded(params) {
7025
7282
  if (!cvSchemaEntry?.schema_definition?.fields)
7026
7283
  continue;
7027
7284
  const cvPolicy = cvSchemaEntry.schema_definition.constraint_violation_policy ?? "reject";
7028
- const violations = collectConstraintViolations(r.fields, cvSchemaEntry.schema_definition.fields);
7285
+ const violations = collectConstraintViolations(r.fields, cvSchemaEntry.schema_definition.fields, { entityType: r.entity_type, schemaVersion: cvSchemaEntry.schema_version });
7029
7286
  if (violations.length === 0)
7030
7287
  continue;
7031
7288
  if (cvPolicy === "reject") {
@@ -7113,35 +7370,40 @@ async function storeStructuredForApiUnguarded(params) {
7113
7370
  const obsSourceLabel = observationSource === undefined || observationSource === null
7114
7371
  ? DEFAULT_OBSERVATION_SOURCE
7115
7372
  : String(observationSource);
7116
- emitObservationCreated({
7373
+ // A null snapshot can mean the id is redirected (merged away): it owns no
7374
+ // entity, so no entity event is announced under it. This is the same
7375
+ // ownership check MCP store uses (resolveOwnedObservations === null).
7376
+ // A new entity cannot be merged away, so it always announces itself. If
7377
+ // the check itself fails for an existing entity we cannot tell, and the
7378
+ // safer choice is to omit the entity event: observation.created still
7379
+ // goes out, whereas a phantom entity.updated under a tombstone id would
7380
+ // mislead subscribers.
7381
+ let emitEntityEvent = true;
7382
+ if (!snapshotAfter && r.trace.action !== "created") {
7383
+ try {
7384
+ const { resolveOwnedObservations } = await import("./services/attachment_resolution.js");
7385
+ emitEntityEvent = (await resolveOwnedObservations(r.entity_id, userId)) !== null;
7386
+ }
7387
+ catch (ownershipErr) {
7388
+ logger.warn(`Ownership check failed for ${r.entity_id}: ${ownershipErr}`);
7389
+ emitEntityEvent = false;
7390
+ }
7391
+ }
7392
+ emitStoreWriteEvents({
7117
7393
  user_id: userId,
7118
7394
  entity_id: r.entity_id,
7119
7395
  entity_type: r.entity_type,
7120
7396
  observation_id: obsRow.id,
7121
7397
  timestamp: emitTs,
7398
+ is_new_entity: r.trace.action === "created",
7399
+ prior_snapshot: priorSnapshot,
7400
+ snapshot_after: snapshotAfter,
7401
+ emit_entity_event: emitEntityEvent,
7122
7402
  source_id: observationSourceId,
7123
7403
  idempotency_key: idempotencyKey,
7124
7404
  observation_source: obsSourceLabel,
7125
7405
  source_peer_id: sourcePeerId ?? undefined,
7126
7406
  });
7127
- if (snapshotAfter) {
7128
- const isNewEntity = r.trace.action === "created";
7129
- emitEntitySnapshotChange({
7130
- user_id: userId,
7131
- entity_id: r.entity_id,
7132
- entity_type: r.entity_type,
7133
- event_type: isNewEntity ? "entity.created" : "entity.updated",
7134
- timestamp: emitTs,
7135
- observation_id: obsRow.id,
7136
- fields_changed: isNewEntity
7137
- ? undefined
7138
- : shallowFieldsChanged(priorSnapshot, snapshotAfter),
7139
- source_id: observationSourceId,
7140
- idempotency_key: idempotencyKey,
7141
- observation_source: obsSourceLabel,
7142
- source_peer_id: sourcePeerId ?? undefined,
7143
- });
7144
- }
7145
7407
  // Schema-driven auto-linking: if the entity's active schema declares
7146
7408
  // reference_fields, create typed relationships to the referenced
7147
7409
  // entities (REFERS_TO by default). Silent fallback when no schema or no
@@ -7190,6 +7452,7 @@ async function storeStructuredForApiUnguarded(params) {
7190
7452
  entityType: r.entity_type,
7191
7453
  fields: r.fields,
7192
7454
  schema: schemaEntry2.schema_definition,
7455
+ schemaVersion: schemaEntry2.schema_version,
7193
7456
  userId,
7194
7457
  sourceId: observationSourceId,
7195
7458
  idempotencyKey,
@@ -7283,9 +7546,10 @@ async function storeStructuredForApiUnguarded(params) {
7283
7546
  // that on the keyed source so a replay of this key knows the write finished
7284
7547
  // (#2144). Before this point a replay resumes the write instead of reporting
7285
7548
  // whatever happened to land.
7549
+ let storeWriteCompletion = { state: "complete" };
7286
7550
  if (commit && storageResult) {
7287
- const { markStoreWriteComplete } = await import("./services/store_write_state.js");
7288
- await markStoreWriteComplete(storageResult.sourceId, userId);
7551
+ const { confirmStoreWriteComplete } = await import("./services/store_write_state.js");
7552
+ storeWriteCompletion = await confirmStoreWriteComplete(storageResult.sourceId, userId);
7289
7553
  }
7290
7554
  // R3: aggregate non-fatal resolver warnings across the batch so callers
7291
7555
  // (agents, Inspector, CI) can audit identity quality without walking every
@@ -7442,7 +7706,10 @@ async function storeStructuredForApiUnguarded(params) {
7442
7706
  const cvPolicy = schemaDef.constraint_violation_policy ?? "reject";
7443
7707
  if (cvPolicy === "warn") {
7444
7708
  const { collectConstraintViolations: _cvCollect } = await import("./services/field_constraints.js");
7445
- const warnViolations = _cvCollect(r.fields, schemaDef.fields);
7709
+ const warnViolations = _cvCollect(r.fields, schemaDef.fields, {
7710
+ entityType: r.entity_type,
7711
+ schemaVersion: schemaEntry?.schema_version,
7712
+ });
7446
7713
  for (const v of warnViolations) {
7447
7714
  schemaStoreWarnings.push({
7448
7715
  code: "CONSTRAINT_VIOLATION",
@@ -7668,6 +7935,10 @@ async function storeStructuredForApiUnguarded(params) {
7668
7935
  observations_created: commit ? createdEntities.length : 0,
7669
7936
  entities: createdEntities,
7670
7937
  relationships_created: relationshipsCreated,
7938
+ ...storeWriteCompletionResponseFields(storeWriteCompletion, {
7939
+ hasInterpretation: Boolean(interpretation),
7940
+ hasIdempotencyKey: Boolean(idempotencyKey),
7941
+ }),
7671
7942
  ...(relationshipsRefused.length > 0 ? { relationships_refused: relationshipsRefused } : {}),
7672
7943
  ...(aggregatedWarnings.length > 0 ? { warnings: aggregatedWarnings } : {}),
7673
7944
  ...(schemaStoreWarnings.length > 0 ? { store_warnings: schemaStoreWarnings } : {}),
@@ -9418,7 +9689,7 @@ const handleIssuesAddMessageHttp = async (req, res) => {
9418
9689
  try {
9419
9690
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
9420
9691
  const userId = principal.kind === "guest"
9421
- ? (await resolveGuestScopedEntityAccess(principal, parsed.data.entity_id?.trim() || "", "issue")).userId
9692
+ ? (await resolveGuestPolicyGovernedEntityAccess(principal, parsed.data.entity_id?.trim() || "", "issue")).userId
9422
9693
  : await getAuthenticatedUserId(req, parsed.data.user_id);
9423
9694
  // Agent grants on the owner path: a thread message is an issue-thread
9424
9695
  // write (and a GitHub comment). The in-process operations layer below does
@@ -9593,7 +9864,7 @@ const handleIssuesGetStatusHttp = async (req, res) => {
9593
9864
  const principal = await resolveRoutePrincipal(req, ["user", "guest"]);
9594
9865
  const issueEntityId = parsed.data.entity_id?.trim() || "";
9595
9866
  const userId = principal.kind === "guest"
9596
- ? (await resolveGuestScopedEntityAccess(principal, issueEntityId, "issue")).userId
9867
+ ? (await resolveGuestPolicyGovernedEntityAccess(principal, issueEntityId, "issue")).userId
9597
9868
  : await getAuthenticatedUserId(req, parsed.data.user_id);
9598
9869
  const { createOperations } = await import("./core/operations.js");
9599
9870
  const { NeotomaServer } = await import("./server.js");
@@ -10049,6 +10320,12 @@ app.post("/update_schema_incremental", async (req, res) => {
10049
10320
  }
10050
10321
  catch (err) {
10051
10322
  const code = err?.code;
10323
+ if (err instanceof SchemaPatternRefusalError) {
10324
+ return sendError(res, 400, "SCHEMA_VALIDATION_FAILED", err.message, {
10325
+ hint: err.remedy,
10326
+ refusal: err.refusal,
10327
+ });
10328
+ }
10052
10329
  if (code === "ERR_FORBIDDEN_ENTITY_TYPE" || code === "ERR_PLURAL_ENTITY_TYPE") {
10053
10330
  return sendError(res, 400, code, err.message);
10054
10331
  }
@@ -10278,6 +10555,12 @@ app.post("/register_schema", async (req, res) => {
10278
10555
  const code = err?.code;
10279
10556
  const message = err instanceof Error ? err.message : String(err);
10280
10557
  logWarn("ValidationError:register_schema", req, { error: message });
10558
+ if (err instanceof SchemaPatternRefusalError) {
10559
+ return sendError(res, 400, "SCHEMA_VALIDATION_FAILED", message, {
10560
+ hint: err.remedy,
10561
+ refusal: err.refusal,
10562
+ });
10563
+ }
10281
10564
  if (code === "ERR_FORBIDDEN_ENTITY_TYPE" || code === "ERR_PLURAL_ENTITY_TYPE") {
10282
10565
  return sendError(res, 400, code, message);
10283
10566
  }
@@ -10738,7 +11021,7 @@ app.post("/subscribe", guestWriteRateLimit, async (req, res) => {
10738
11021
  const granted = new Set(guestScope);
10739
11022
  const withinScope = requested.length > 0 && requested.every((id) => granted.has(id));
10740
11023
  if (!withinScope) {
10741
- return sendError(res, 403, "FORBIDDEN", "Guest access token does not grant entity_ids for this subscription");
11024
+ throw new GuestTokenScopeError();
10742
11025
  }
10743
11026
  // Guest delivery must stay bound to the guest credential's lifetime.
10744
11027
  // Only SSE delivery revalidates the token on every event; webhook and
@@ -10791,7 +11074,7 @@ app.post("/unsubscribe", guestWriteRateLimit, async (req, res) => {
10791
11074
  subscription_id: parsed.data.subscription_id,
10792
11075
  });
10793
11076
  if (!target || !subscriptionWithinGuestScope(guestScope, target.watch_entity_ids)) {
10794
- return sendError(res, 403, "FORBIDDEN", "Guest access token does not grant access to this subscription");
11077
+ throw new GuestTokenScopeError();
10795
11078
  }
10796
11079
  }
10797
11080
  // Agent grants: unsubscribing corrects the subscription (active=false).
@@ -10842,8 +11125,12 @@ app.post("/get_subscription_status", async (req, res) => {
10842
11125
  userId,
10843
11126
  subscription_id: parsed.data.subscription_id,
10844
11127
  });
10845
- if (!row ||
10846
- (guestScope !== null && !subscriptionWithinGuestScope(guestScope, row.watch_entity_ids))) {
11128
+ if (guestScope !== null &&
11129
+ row &&
11130
+ !subscriptionWithinGuestScope(guestScope, row.watch_entity_ids)) {
11131
+ throw new GuestTokenScopeError();
11132
+ }
11133
+ if (!row) {
10847
11134
  return res.json({ subscription: null });
10848
11135
  }
10849
11136
  return res.json({ subscription: redactSubscriptionForClient(row) });
@@ -10944,8 +11231,12 @@ app.get("/events/stream", async (req, res) => {
10944
11231
  const { subscriptionMatchesEvent } = await import("./services/subscriptions/subscription_types.js");
10945
11232
  const { getEventsAfterSeq, hasDurableCursor } = await import("./services/subscriptions/event_log.js");
10946
11233
  const sub = await getSubscriptionStatus({ userId, subscription_id });
10947
- if (!sub ||
10948
- (guestScope !== null && !subscriptionWithinGuestScope(guestScope, sub.watch_entity_ids))) {
11234
+ if (guestScope !== null &&
11235
+ sub &&
11236
+ !subscriptionWithinGuestScope(guestScope, sub.watch_entity_ids)) {
11237
+ throw new GuestTokenScopeError();
11238
+ }
11239
+ if (!sub) {
10949
11240
  return sendError(res, 404, "NOT_FOUND", "subscription not found");
10950
11241
  }
10951
11242
  if (!sub.active) {
@@ -10957,8 +11248,13 @@ app.get("/events/stream", async (req, res) => {
10957
11248
  const guestAccessToken = principal.kind === "guest" ? principal.guestId.accessToken : undefined;
10958
11249
  const authorize = guestAccessToken
10959
11250
  ? async () => {
10960
- const { validateGuestAccessToken } = await import("./services/guest_access_token.js");
10961
- const grant = await validateGuestAccessToken(guestAccessToken);
11251
+ let grant;
11252
+ try {
11253
+ grant = await validateGuestToken(guestAccessToken);
11254
+ }
11255
+ catch {
11256
+ return false; // records unreadable: stop the stream, never grant
11257
+ }
10962
11258
  return (grant !== null &&
10963
11259
  grant.entity_ids.length > 0 &&
10964
11260
  subscriptionWithinGuestScope(grant.entity_ids, sub.watch_entity_ids));