@jini-ai/core 0.4.9 → 0.6.10

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @jini-ai/core
 
+## 0.6.10
+
+### Patch Changes
+
+- 22f0619: Export baseline agent-failure token patterns, credential-directory deny
+  segments, and local-owner proxy markers for reuse by consumers.
+  Preserve existing vocabulary and redaction behavior.
+- 82ed2d3: Expose the React-free fetch-query contracts/cache at @jini-ai/core/fetch; UI keeps deprecated direct type re-exports. Build core before UI and publish before consumers adopt the subpath.
+- 5a3de86: Add optional `expectedRevisionSeq` options to settings `set(required, options)` and
+  `clear(required, options)`. Compare the addressed scope's stored value revision under
+  the existing transaction's ledger lock, throwing `SettingsRevisionConflictError`
+  with expected and actual sequences on mismatch and rolling back the write and revision.
+  Revision 0 represents a missing row; cleared rows retain their revision. Omitting
+  the option preserves unconditional writes. Available through `@jini-ai/core/settings`
+  and the existing `@jini-ai/cms/settings` compatibility re-export.
+
 ## 0.4.9 — 2026-10-22
 
 - 2026-10-22: Provider registry, ObjectStore contract with object_store registry and deferObjectStore, default-on batch tool eligibility, coverage.
@@ -56,7 +72,6 @@
 - Move the domain-independent catalog/input/schema/risk/confirmation registration kit into the root entry, with its behavior contracts. Domain-specific authorization and denial errors remain outside the kernel.
 - Use the existing named argument surface directly; primitive, Result and tool catalog types remain canonical in core.
 
-
 ### Shared kernel
 
 - Add `./primitives` with canonical time, ID, JSON, HTTP, logger and result contracts,
@@ -80,7 +95,6 @@
 - Origin diagnostics use `Pick<Logger, 'warn'>` rather than a duplicate logger interface.
   The alias name `OriginValidationLoggerPort` remains available with the shared shape.
 
-
 - Add transport-neutral gated mutations with required token generation/TTL and async
   authorization, identity and token-store ports; preserve verified-plan handoff and
   single-use redemption, with atomic explicit expiry and duplicate-issuance rejection.

package/README.md

@@ -44,6 +44,11 @@ peer used only by `@jini-ai/core/settings/express`; install it in hosts mounting
 
 ## Usage
 
+The root exports baseline security vocabulary: `AGENT_FAILURE_SECRET_SHAPE_RE`,
+`CREDENTIAL_FILE_DENY_SEGMENTS`, `LOCAL_OWNER_PROXY_MARKER_PREFIXES`, and
+`LOCAL_OWNER_PROXY_MARKER_HEADERS`. Consumers apply these in their existing failure-redaction,
+guarded-file, and local-owner admission policies; the existing redactors are unchanged.
+
 ```ts
 import { bindings, definePack, createDaemon, token, createToolRegistry, registerPackTools } from '@jini-ai/core';
 

package/dist/redact.d.ts

@@ -38,6 +38,34 @@ export interface SecretShapePattern {
 }
 export declare const PEM_PATTERN_NAME = "PEM private key block";
 export declare const SECRET_SHAPE_PATTERNS: readonly SecretShapePattern[];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export declare const AGENT_FAILURE_SECRET_SHAPE_RE: RegExp;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+export declare const CREDENTIAL_FILE_DENY_SEGMENTS: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_PREFIXES: readonly string[];
+export declare const LOCAL_OWNER_PROXY_MARKER_HEADERS: readonly string[];
 export interface SecretRedactionPattern {
     name: string;
     regex: RegExp;

package/dist/redact.js

@@ -52,6 +52,40 @@ export const SECRET_SHAPE_PATTERNS = [
     { name: "Fastmail app password (fm2_)", pattern: /(?<![A-Za-z0-9+/=])fm2_[A-Za-z0-9+/=]{20,}/ },
     { name: PEM_PATTERN_NAME, pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
 ];
+/** Broad token shapes for agent-failure text; consumers retain their plain [REDACTED] pipeline. */
+export const AGENT_FAILURE_SECRET_SHAPE_RE = /\b(?:AIza[\w-]+|AQ\.[\w.\/-]+|sk-[\w.-]+|gh[pousr]_[\w]+|github_pat_[\w]+|ya29\.[\w.-]+|eyJ[\w-]+\.[\w-]+(?:\.[\w-]+)?)/g;
+/**
+ * Exact path SEGMENT names refused at any depth, matched case-insensitively against each segment
+ * of the caller-supplied path (never a substring — a directory named `not-secrets-actually` is not
+ * a match). `secrets` is the owner's explicit example: whatever a site or app tree names its
+ * credentials folder (`sites/**\/secrets/`, `apps/admin/**\/secrets/`, or anywhere else), it never
+ * becomes reachable through this domain. A denied segment is refused by the guarded reader
+ * AND skipped entirely by the `fs_list_files` walk — its contents are never even enumerated,
+ * not merely refused once named. Besides `secrets`, the set names the
+ * well-known credential-store directories a home-directory `custom` root can expose: `.aws`
+ * (`credentials`), `.docker` (`config.json` with registry auth), `.kube` (`config`), and
+ * `gcloud`/`gh` for `.config/gcloud/application_default_credentials.json` and
+ * `.config/gh/hosts.yml`. Denied by SEGMENT rather than by leaf filename on purpose: `config`,
+ * `config.json`, and `hosts.yml` are generic names that appear harmlessly elsewhere, so denying the
+ * directory is the narrower of the two mistakes.
+ *
+ * A host's install-wide site-key directory (2026-09-24) needs the same protection; the host appends it.
+ * Production stores it beside individual site folders on a durable volume; local/dev stores
+ * it below the home directory, reachable through an operator-set `custom` root. Its key backs
+ * site-key administration, webhook/newsletter signing secrets, and permission checks, so the
+ * agent must never read it from disk. Denying the whole directory segment, rather than only
+ * a generated key filename, also prevents `fs_list_files` from enumerating its contents — the
+ * same "never even advertise it" property `secrets` gets above.
+ */
+// Generic credential-store segments only. A host adds its own product-specific key directory
+// (e.g. its install-wide site-key folder) when it builds its deny-list; core stays product-neutral.
+export const CREDENTIAL_FILE_DENY_SEGMENTS = ["secrets", ".aws", ".docker", ".kube", "gcloud", "gh"];
+// A local tunnel has a loopback socket and may rewrite Host; refuse marker presence, even empty.
+export const LOCAL_OWNER_PROXY_MARKER_PREFIXES = ["x-forwarded-", "x-envoy-", "x-ms-"];
+export const LOCAL_OWNER_PROXY_MARKER_HEADERS = [
+    "forwarded", "x-real-ip", "via", "cf-connecting-ip", "true-client-ip", "x-original-host",
+    "x-client-ip", "x-cluster-client-ip", "fastly-client-ip", "tailscale-user-login", "x-original-forwarded-for",
+];
 // Order matters: list specific rules before more general ones. Langfuse
 // keys (`sk-lf-...`) would otherwise be eaten by the generic `sk-...`
 // rule and labeled as a generic OpenAI-style key.

package/dist/settings/errors.d.ts

@@ -18,6 +18,19 @@ export declare class SecretNotSupportedError extends Error {
 }
 export declare class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export declare class SettingsRevisionConflictError extends Error {
+    readonly expectedRevisionSeq: number;
+    readonly actualRevisionSeq: number;
+    constructor(required: {
+        expectedRevisionSeq: number;
+        actualRevisionSeq: number;
+    }, optional?: ErrorOptions);
+}
 export declare class RenameRetypeConflictError extends Error {
 }
 export declare class AliasDepthExceededError extends Error {

package/dist/settings/errors.js

@@ -18,6 +18,21 @@ export class SecretNotSupportedError extends Error {
 }
 export class ValueValidationFailedError extends Error {
 }
+/**
+ * A scoped value changed since the caller's snapshot; read again before retrying.
+ * Both sequences refer to the addressed value row, never the ledger's global watermark.
+ * @example if (error instanceof SettingsRevisionConflictError) await refreshSnapshot();
+ */
+export class SettingsRevisionConflictError extends Error {
+    expectedRevisionSeq;
+    actualRevisionSeq;
+    constructor(required, optional = {}) {
+        super(`Setting revision changed: expected ${required.expectedRevisionSeq}, found ${required.actualRevisionSeq}.`, optional);
+        this.name = "SettingsRevisionConflictError";
+        this.expectedRevisionSeq = required.expectedRevisionSeq;
+        this.actualRevisionSeq = required.actualRevisionSeq;
+    }
+}
 export class RenameRetypeConflictError extends Error {
 }
 export class AliasDepthExceededError extends Error {

package/dist/settings/index.d.ts

@@ -11,11 +11,11 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, type SettingScope, type SettingOwnerKind, type DefinitionStatus, type ValueState, type RevisionEntityKind, type RevisionOp, type SettingValueSchema, type SettingDefinitionRecord, type SettingValueRecord, type SettingRevisionRecord, type SettingScopeContext, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export type { SettingsRepoPort } from "./ports.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { type DefinitionInput, validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, type ResolvedSetting, getEffective, } from "./settings.js";
-export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
+export { type AuthorizeFn, type SettingsWriteServiceDeps, deriveRequiredPermission, type RegisterDefinitionsRequired, registerDefinitions, type SetValueRequired, type SettingsValueWriteOptions, set, type ClearValueRequired, clear, type ResetNamespaceRequired, resetNamespace, type RenameDefinitionRequired, renameDefinition, type RetypeDefinitionRequired, retypeDefinition, type ReconcileDefinitionDefaultRequired, reconcileDefinitionDefault, type DeprecateDefinitionRequired, deprecateDefinition, type TombstoneDefinitionRequired, tombstoneDefinition, } from "./write-service.js";
 export { type PurgeServiceDeps, type PurgeTenantSettingsRequired, purgeTenantSettings, } from "./purge-service.js";
 export { type ChangeFeedViewer, isRevisionVisibleTo, type ChangeFeedBatch, collectChangedNamespaces, } from "./change-feed.js";
 export { type DefinitionOpRequestItem, type DefinitionOpContext, type DefinitionOpHandler, NON_REGISTER_DEFINITION_OP_NAMES, type NonRegisterDefinitionOp, parseNonRegisterDefinitionOp, NON_REGISTER_DEFINITION_OPS, } from "./definitions-dispatch.js";

package/dist/settings/index.js

@@ -11,7 +11,7 @@
  * `SettingsRepoPort` this barrel exports.
  */
 export { SCOPE_BIT, } from "./types.js";
-export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
+export { DefinitionInvalidError, ScopeNotAllowedError, SecretNotSupportedError, ValueValidationFailedError, SettingsRevisionConflictError, RenameRetypeConflictError, AliasDepthExceededError, DefinitionTombstonedError, DefinitionNotFoundError, PurgeRequiredError, ForbiddenError, PrincipalNotFoundError, } from "./errors.js";
 export { InMemorySettingsRepo } from "./repo.memory.js";
 export { validateDefinitionInput, validateValueAgainstSchema, registerCoercer, invalidateDefinitionNamespaceCache, invalidateWorkspaceSettingsCache, resolveDefinitionRaw, resolveDefinition, getEffective, } from "./settings.js";
 export { deriveRequiredPermission, registerDefinitions, set, clear, resetNamespace, renameDefinition, retypeDefinition, reconcileDefinitionDefault, deprecateDefinition, tombstoneDefinition, } from "./write-service.js";

package/dist/settings/ports.d.ts

@@ -68,7 +68,13 @@ export interface SettingsRepoPort {
         principalId: UUID;
         settingId: UUID;
     }): Promise<void>;
-    /** Appends a revision and returns its assigned `seq` (used to stamp the paired value row). */
+    /**
+     * Appends a revision and returns its assigned `seq` (used to stamp the paired value row).
+     * Inside a transaction, serialize revision writers until that enclosing transaction ends:
+     * `set`/`clear` compare the stored value's seq AFTER this call, so the lock must cover the
+     * comparison and value save too. SQLite's write transaction and Postgres's transaction-scoped
+     * ledger lock provide this; memory refuses overlapping transactions.
+     */
     appendRevision(record: Omit<SettingRevisionRecord, "seq">): Promise<number>;
     listRevisions(required: {
         settingId: UUID;

package/dist/settings/write-service.d.ts

@@ -110,8 +110,21 @@ export interface SetValueRequired {
         requiredPermissionOverride?: string | undefined;
     };
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function set(required: SetValueRequired): Promise<{
+/** Optional concurrency guard shared by `set` and `clear`. */
+export interface SettingsValueWriteOptions {
+    /** Compare the addressed layer's stored seq, including cleared rows; 0 means no stored row.
+     * Omission preserves unconditional writes. Defaults, inherited values and definition revisions
+     * do not count. A mismatch throws SettingsRevisionConflictError and rolls back the write.
+     */
+    readonly expectedRevisionSeq?: number | undefined;
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function set(required: SetValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     value: JsonValue;
     revisionSeq: number;
 }>;
@@ -135,8 +148,14 @@ export interface ClearValueRequired {
         authWorkspaceId?: UUID | undefined;
     };
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export declare function clear(required: ClearValueRequired): Promise<{
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export declare function clear(required: ClearValueRequired, optional?: SettingsValueWriteOptions): Promise<{
     revisionSeq: number;
 }>;
 export interface ResetNamespaceRequired {

package/dist/settings/write-service.js

@@ -1,5 +1,5 @@
 import { nowIso as kernelNowIso } from "../primitives/index.js";
-import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, ValueValidationFailedError, } from "./errors.js";
+import { AliasDepthExceededError, DefinitionInvalidError, DefinitionNotFoundError, DefinitionTombstonedError, ForbiddenError, PrincipalNotFoundError, RenameRetypeConflictError, ScopeNotAllowedError, SettingsRevisionConflictError, ValueValidationFailedError, } from "./errors.js";
 import { invalidateDefinitionNamespaceCache, resolveDefinitionRaw, validateDefinitionInput, validateValueAgainstSchema, } from "./settings.js";
 import { SCOPE_BIT } from "./types.js";
 /**
@@ -148,8 +148,33 @@ async function assertTargetPrincipalInWorkspace(deps, input) {
         throw new PrincipalNotFoundError(`principal '${input.principalId}' was not found in workspace '${input.workspaceId}'`, input.principalId, input.workspaceId);
     }
 }
-/** chokepoint write: authorize -> validate -> value + revision, same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function set(required) {
+/**
+ * Check the addressed value after appendRevision has taken the ledger lock. On Postgres, a read
+ * before that lock can see the same old seq in two READ COMMITTED transactions and lose an update.
+ * The caller's enclosing transaction rolls the appended revision back on conflict.
+ * @complexity At most one scoped value read; no reads when the option is omitted.
+ */
+async function assertExpectedRevision(required, optional = {}) {
+    if (optional.expectedRevisionSeq === undefined)
+        return;
+    const { repo, settingId, input } = required;
+    const current = input.scope === "global"
+        ? await repo.getGlobalValue(settingId)
+        : input.scope === "workspace"
+            ? await repo.getWorkspaceValue({ workspaceId: input.workspaceId, settingId })
+            : await repo.getUserValue({ workspaceId: input.workspaceId, principalId: input.principalId ?? input.callerPrincipalId, settingId });
+    const actualRevisionSeq = current?.seq ?? 0;
+    if (actualRevisionSeq !== optional.expectedRevisionSeq) {
+        throw new SettingsRevisionConflictError({ expectedRevisionSeq: optional.expectedRevisionSeq, actualRevisionSeq });
+    }
+}
+/**
+ * Authorize -> validate -> value + revision in one transaction. An optional expectedRevisionSeq
+ * refuses a stale scoped value and rolls back its revision; omission keeps unconditional writes.
+ * @example await set({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function set(required, optional = {}) {
     const { deps, input } = required;
     const permission = input.requiredPermissionOverride ??
         deriveRequiredPermission({
@@ -190,6 +215,7 @@ export async function set(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,
@@ -222,8 +248,14 @@ export async function set(required) {
     });
     return result;
 }
-/** chokepoint write: authorize -> value + revision (state='cleared'), same tx. See docs/decisions/DR-003-settings-ledger-invariants.md. */
-export async function clear(required) {
+/**
+ * Authorize -> cleared value + revision in one transaction; the optional concurrency guard has
+ * the same semantics as `set`. With skipTransaction, the enclosing caller must propagate errors
+ * so its transaction rolls back the appended revision on conflict.
+ * @example await clear({ deps, input }, { expectedRevisionSeq: snapshotSeq });
+ * See docs/decisions/DR-003-settings-ledger-invariants.md.
+ */
+export async function clear(required, optional = {}) {
     const { deps, input } = required;
     if (!input.skipAuthorize) {
         const permission = deriveRequiredPermission({
@@ -262,6 +294,7 @@ export async function clear(required) {
             changeSetId: null,
             createdAt: now,
         });
+        await assertExpectedRevision({ repo: deps.repo, settingId: definition.settingId, input }, optional);
         const base = {
             settingId: definition.settingId,
             scope: input.scope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jini-ai/core",
-  "version": "0.4.9",
+  "version": "0.6.10",
   "description": "The Jini kernel: typed DI tokens, pack composition and lifecycle, the tool registry, redaction, and origin/API-token auth primitives. Zero dependencies.",
   "license": "Apache-2.0",
   "repository": {