dotmem 0.0.5 → 0.0.8

package/SECURITY.md

@@ -0,0 +1,525 @@
+# Security & Encryption
+
+This document covers dotmem's optional encryption layer, client-side multitenancy, and general security posture. For the short version, see the **Security** section in the main [README](./README.md).
+
+---
+
+## Nothing is encrypted by default
+
+This applies to every layer: `state`, `store`, `session`, `idb`, `memory`, `sqlite`. Treat browser storage as client-controlled unless you explicitly opt in.
+
+Core declares no production dependencies in package.json. `memorio` is listed under devDependencies, but the built ESM/CJS output imports it as an external runtime module; a published install therefore needs `memorio` available unless packaging changes. No `eval`, no dynamic code execution, no bundled telemetry, sanitized keys, validated inputs, bounded journal entries, UUID-based session identifiers. Independently checkable via Socket.dev / Snyk. (The optional MCP stdio entrypoint is the one declared-dependency surface: `zod` and `@modelcontextprotocol/server`.)
+
+---
+
+## The encryption layer
+
+dotmem ships an optional encryption layer built on the **Web Crypto API** (`crypto.subtle`): AES-GCM for authenticated encryption, PBKDF2 for password-based key derivation. It is opt-in - no layer encrypts by default, so the common case stays transparent and fast.
+
+All `dotmem.encryption` operations are **asynchronous by design** - the Web Crypto API runs cryptographic work on a separate internal thread managed by the browser/runtime, so `deriveKey()`, `encrypt()`, and `decrypt()` return Promises that never block the main thread. PBKDF2 derivation at the NIST SP 800-132-recommended 600,000 iterations typically completes in under 300ms on mid-range hardware. No explicit Web Worker offload is needed.
+
+### Encrypt a value
+
+```ts
+import { dotmem } from 'dotmem'
+
+// Derive a key from a password (PBKDF2, 600k iterations - NIST SP 800-132)
+const key = await dotmem.encryption.deriveKey('my-password', 'per-tenant-salt')
+// or generate one directly, without a password:
+const freshKey = await dotmem.encryption.generateKey()
+const freshSalt = dotmem.encryption.generateSalt()
+
+// Encrypt → envelope object { __dotmem_encrypted, alg, iv, data }
+const envelope = await dotmem.encryption.encrypt({ token: 'abc123' }, key)
+
+// Decrypt - wrong key rejects rather than returning garbage
+const original = await dotmem.encryption.decrypt(envelope, key)
+// → { token: 'abc123' }
+
+// Check a value before trying to decrypt it
+dotmem.encryption.isEncrypted(envelope) // true - checks the __dotmem_encrypted flag
+dotmem.encryption.isAvailable() // false in environments without Web Crypto (e.g. old runtimes)
+```
+
+For the common "encrypt with a password, get a string back" case, skip manual key derivation:
+
+```ts
+const cipherText = await dotmem.encryption.encryptWithPassword({ token: 'abc123' }, 'my-password')
+const plain = await dotmem.encryption.decryptWithPassword(cipherText, 'my-password')
+```
+
+Both accept/return an envelope object (not a JSON string when you already have a key):
+
+```ts
+const envelope = await dotmem.encryption.encrypt({ token: 'abc123' }, key)
+const plain = await dotmem.encryption.decrypt(envelope, key) // returns the original value
+```
+
+**Key import/export** for storing CryptoKey material securely (e.g. in an httpOnly cookie):
+
+```ts
+const key = await dotmem.encryption.generateKey()
+const { key: b64, iv } = await dotmem.encryption.exportKey(key)
+// Store b64 securely, then restore later:
+const restoredKey = await dotmem.encryption.importKey(b64, iv)
+```
+
+### Store with at-rest encryption
+
+```ts
+// Per-call encryption (opt-in)
+await store.set('api_token', secretValue, { encrypt: key })
+const token = await store.get('api_token', { decrypt: key })
+
+// Or configure a default key for automatic encryption:
+store.config({ encryptionKey: key })
+await store.set('api_token', secretValue) // encrypted transparently
+const token = await store.get('api_token') // decrypted transparently
+```
+
+`session` supports the same `config` and per-call opts.
+
+> ⚠️ **Sync vs async changes once encryption is on.** Without encryption, `store.get`/`store.set` (and `session`'s equivalents) are synchronous - they return the value directly. As soon as either call touches `encrypt`/`decrypt` (per-call, or because a default `encryptionKey` is configured), both become asynchronous and return a `Promise`. Code written against the plain synchronous API will silently receive a `Promise` instead of a value if encryption is turned on later - always `await` `store.get`/`store.set` defensively if there's any chance encryption gets enabled down the line.
+
+---
+
+## Contexts are not authorization
+
+```ts
+dotmem.createContext('tenant-123')
+```
+
+Contexts organize and isolate application concerns by namespace-prefixing keys - they are **not** a security boundary. Any script running in the same JS runtime can attempt operations against another context. Real tenant isolation belongs at the auth/backend layer.
+
+---
+
+## Encrypted multitenancy
+
+Pass an `encryptionKey` to `createContext()` and the tenant's isolated `store`/`session` automatically encrypt on write and decrypt on read:
+
+```ts
+const tenantKey = await dotmem.encryption.deriveKey(tenantPassword, tenantSalt)
+
+const ctx = dotmem.createContext('tenant-123', { encryptionKey: tenantKey })
+
+// Values are encrypted at rest within this context's namespace
+await ctx.store.set('secrets', { apiKey: '…' })
+const secrets = await ctx.store.get('secrets') // decrypted transparently
+
+// Another tenant with a different key can't read this data
+const otherCtx = dotmem.createContext('tenant-456', { encryptionKey: otherKey })
+const leaked = await otherCtx.store.get('dotmem_store_secrets') // fails to decrypt
+```
+
+This adds a cryptographic wall on top of the namespace prefix: even if a tenant's key prefix is guessed, the ciphertext is unreadable without the key. It still doesn't replace backend authorization - see above.
+
+> ⚠️ **`cache` is never encrypted, even inside an encrypted context.** `createContext(name, { encryptionKey })` only encrypts that context's `store` and `session` - its `cache` stays volatile, in-memory, and in plaintext regardless. Don't put anything in `ctx.cache` you wouldn't put in unencrypted `cache`.
+
+`dotmem.isolate()` is a thin alias for `createContext()` and accepts the same `{ encryptionKey }` option.
+
+> **Key management is yours.** Derive keys from authenticated session material or generate them with `dotmem.encryption.generateKey()`. Never hardcode keys in client bundles.
+
+---
+
+## Global API security
+
+dotmem does **not** expose its APIs on `globalThis` by default. The opt-in entrypoint `import 'dotmem/global'` installs `state`, `store`, `session`, `cache`, `idb`, `sqlite`, and `observer` on `globalThis` - this is an explicit consumer choice, never inferred from `NODE_ENV` or bundler environment variables. `useObserver` is a React hook and is **not** installed on `globalThis`; it is exported only from the `dotmem/react` entrypoint and requires React as an optional peer.
+
+For application code, prefer explicit named imports:
+
+```ts
+import { state } from 'dotmem'
+```
+
+---
+
+## Code-level hardening
+
+- No hardcoded credentials, API keys, or secrets anywhere in the codebase or build output.
+- Session IDs use a secure random source with graceful fallback: `crypto.randomUUID` → `crypto.getRandomValues` → a documented fallback if neither is available.
+- Public APIs validate their inputs rather than trusting caller-supplied shapes.
+- Global objects installed via `dotmem/global` use `Object.defineProperty` with `enumerable: false` where applicable, rather than plain assignment.
+- No obfuscated or minified-beyond-readability code shipped in a way that would hide behavior from review.
+
+---
+
+## Store integrity and acquisition size limits
+
+The store is the only durable copy of acquired experience, so a refused write
+must never be able to damage it.
+
+- **The writer stays below the reader.** The MEM package reader enforces hard
+ limits (8 MiB per entry, 10 MiB per package, 25 MiB uncompressed). The
+ writer enforces stricter limits, with 1 MiB of margin, so a package this
+ library produces is always readable by this library.
+- **Nothing is published before it is verified.** A write goes to a temporary
+ file in the same directory as the store, is `fsync`ed, is read back and
+ decoded, and only then replaces the store. A package the library cannot read
+ never becomes the store. A failed write removes its temporary file.
+- **The last valid version is kept.** Every successful write leaves the
+ previous valid store next to it as `<store>.bak`. The backup is written from
+ the current file only when that file is a valid package, and it is never
+ discovered as a memory source.
+- **Size limits are checked before the write.** The acquisition boundary
+ refuses a payload above 1 MiB per field or 4 MiB per claim; the MCP surface
+ refuses above 256 KiB per field or 1 MiB per claim. The limits are measured
+ on the raw payload as well as on the sanitized one: a field that
+ sanitization would replace with a placeholder is still a field the caller
+ sent. The refusal carries a stable code and never a filesystem path.
+- **A store has a ceiling.** A store above 4 MiB of content is refused with
+ `DOTMEM_STORE_TOO_LARGE`, and the previous valid version stays in place.
+- **A session has a ceiling.** One MCP session accepts 100 acquisitions
+ (`DOTMEM_SESSION_ACQUIRE_LIMIT`). The refusal is not retryable: the
+ condition is not transient.
+- **Concurrent writes are safe, not silent.** Writes to one store are
+ serialized in process, in arrival order. A write that loses a race against
+ a writer in another process is refused with `DOTMEM_CONCURRENT_WRITE` and
+ `retryable: true`. dotmem never retries the operation on its own.
+- **A delete deletes.** Deleting the writable store removes its backup and
+ its temporary files with it, so deleted content does not survive in
+ `<store>.bak`.
+
+The limits are published in the acquisition contract
+(`npx dotmem policy contract acquire --json`).
+
+## The MCP write tool is opt-in
+
+Reading memory through MCP is safe by construction: the read tools return
+data that the host must verify, and the projection carries the untrusted
+markers. Writing memory changes the durable state of the operator's
+machine.
+
+- `dotmem_acquire` is registered only when the server environment sets
+ `DOTMEM_MCP_WRITE=1`.
+- `dotmem_continuity` write actions (`checkpoint`, `add-open-loop`,
+ `resolve-open-loop`) require `DOTMEM_MCP_WRITE=1`. Read actions
+ (`status`, `summaries`, `open-loops`, `evaluate`) are always available.
+- Without the flag, the server exposes `dotmem_context`, `dotmem_rules`,
+ and `dotmem_continuity` (read actions only). The write tools are not in
+ `tools/list`, and calling them by name answers `Tool <name> not found`.
+- The flag is read once, when the server starts. Changing it requires
+ restarting the server.
+- The library API (`memory.acquire()`) and the CLI (`npx dotmem acquire`)
+ are not gated: the gate is on the surface a third-party host reaches
+ without a human typing a command.
+
+A host configuration that grants the write tool grants it on purpose, in a
+file the operator reads.
+
+---
+
+## Memory / Policy / Authority separation (acquired experience)
+
+For persistent acquired experience, memory is data, policy governs how memory
+may influence behavior, and authority is who may change policy. The three are
+separate authority domains in code:
+
+- ordinary acquisition writes memory only, and can never
+ write policy
+- policy is written only through the privileged `PolicyStore` path, which
+ requires explicit HI or operator authority on every write
+- a governed claim never selects its own enforcement tier, effective tiers
+ are resolved only from the policy store, and a `tier` field inside an
+ acquired knowledge payload is stripped at the write boundary
+- deletion is a modification: `memory.clear()` is memory-scoped and never
+ deletes policy documents; policy removal requires `memory.policy.clear(authority)`
+- every durable write crosses one canonical acquisition boundary, so direct and
+ staged acquisition cannot diverge in enforcement; effective tiers
+ are resolved only from the policy store, and a payload `tier` field is
+ stripped at the write boundary
+
+Enforcement tiers: `context` (soft influence, miss correctable), `precondition`
+(block the action and ask HI), `hard-precondition` (block the action; no
+conversational override). Events are evaluated at decision time
+(`event=artifact.write`, `event=memory.acquire`), not pushed into context. The
+evaluation API has no override parameter and rejects override option keys
+outright.
+
+Policy conditions are evaluated against the action payload, not merely
+discovered: `satisfied` (the payload deterministically meets the condition)
+allows the action; `violated` and `unresolved` (no payload, or a language that
+cannot be established deterministically) block-and-ask and are never assumed
+satisfied. `memory.acquire()` itself evaluates the `memory.acquire` event against
+the payload about to be written and blocks with
+`PolicyPreconditionViolationError` on a violated or unresolved precondition.
+Language detection is a deterministic lexicon heuristic that reports `und`
+rather than guessing.
+
+The machine-readable operator contract is exported as
+`MEMORY_PROJECTION_CONTRACT` and printed by `npx dotmem policy contract`.
+Deterministic write-time checks include schema validation, known secret
+shapes, entropy/size bounds, and a UTF-8/Latin-1 collision (mojibake)
+rejection. No semantic hostility scoring exists, by design.
+
+Full implementation record:
+`.project/DOTMEM_MEMORY_POLICY_AUTHORITY_SEPARATION.md`.
+
+### Privileged out-of-band policy override
+
+The privileged override changes *effective* policy state; it never mutates the
+base policy. It is a hardened path by construction:
+
+- ordinary chat cannot grant an override; the evaluation API has no override
+ parameter and still rejects override option keys outright
+- `memory.acquire` cannot grant an override: the acquisition boundary reads the
+ store's override set as effective state, and no payload, claim, conversation,
+ retrieved text, or tool-output field participates in override resolution
+- the target policy, its `revision`, and its canonical semantic `fingerprint`
+ are derived from the store, never accepted from the payload; a changed,
+ deleted, or recreated policy leaves the override `STALE` or `INERT`, so an
+ override never silently weakens a policy it no longer describes
+- authority hierarchy is enforced at grant time: an operator authority cannot
+ relax an HI-owned policy, and revocation follows the same ordering (HI
+ revokes any override; an operator only its own)
+- `expiresAt` is mandatory and the window is bounded (`MAX_OVERRIDE_WINDOW_MS`);
+ expiry and revoke both restore the base policy, and exactly one active
+ override exists per target (a new grant atomically supersedes)
+- every mutation runs inside a cross-process exclusive-create policy lock
+ (owner identity, bounded retry, audited stale-lock break, optimistic
+ `basedOnRevision` inside the lock, fail-closed when exclusive creation cannot
+ be verified) and is committed in one atomic document write together with its
+ durable in-document audit record. An active override without an applied audit
+ record makes the document unloadable: no override is effective without a
+ recoverable durable audit record. The privileged reset preserves the audit
+ trail with a terminal `clear` entry.
+
+Residual risk, honestly stated: the audit trail and policy documents live in
+the same storage tree as everything else, so filesystem-level tamper isolation
+and policy signing remain open work — the mechanism makes unauthorized
+relaxation *attributable*, not undetectable-by-absence.
+
+---
+
+## Supply chain
+
+- Declared production dependencies: none in the root package.json; `memorio` is a devDependency. The built output imports `memorio` as an external runtime module, so it must be available to a published install unless packaging changes. Do not infer zero runtime dependencies from package.json alone.
+- Dev dependencies are audited periodically (`npm audit` and equivalent).
+- Package integrity is checkable independently via Socket.dev / Snyk before you adopt a given version.
+
+> If you require a specific minimum Socket.dev/Snyk score or a documented audit trail as part of a procurement process, verify the current score yourself at adoption time - this document doesn't pin a number that could go stale.
+
+### Software Bill of Materials (SBOM)
+
+dotmem publishes a **CycloneDX 1.6** SBOM (`bom.json`) as a release artifact. The SBOM is
+generated from `package.json` + `package-lock.json` using `@cyclonedx/cyclonedx-npm` and is
+emitted into `dist/` so it is included in every published tarball.
+
+- **Regenerate locally:** `npm run sbom` (produces `dist/bom.json`). Requires Node ≥ 20.18.
+- **CI:** SBOM generation is wired into `.gitea/workflows/npm.yml` as a release step (tag push),
+ running after `npm run build` and tests, before `npm publish ./dist`.
+- **Format:** CycloneDX JSON 1.6 — components carry PURL, SPDX license, digests, and version.
+ produces a separate `.vsix` and has its own dependency tree; that SBOM is generated by a parallel
+ `cyclonedx-npm` invocation in the extension's packaging step.
+
+> ⚠️ The unscoped npm package `cyclonedx-npm` is a known **dependency-confusion placeholder** and must
+> never be used. The official tool is `@cyclonedx/cyclonedx-npm`. A compliance test
+ > (`tests/vitest/tests/contracts/sbom.test.ts`) verifies SBOM integrity.
+
+---
+
+## Semantic and epistemic security — OPEN research
+
+Package integrity and Ed25519 authenticity do not establish truth, authority, permission, or current
+applicability. For persistent acquired experience, keep these distinctions explicit:
+
+```text
+IDENTITY != CLAIMED IDENTITY
+ROLE != CLAIMED ROLE
+PROVENANCE != TRUTH
+AUTHENTICITY != AUTHORITY
+AUTHORITY != PERMISSION
+MEMORY != INSTRUCTION
+SIGNED != TRUSTED != TRUE
+```
+
+For the public acquired-experience workflow, also preserve these operational boundaries:
+
+```text
+DISCOVERED != APPLICABLE
+PROJECTED != CURRENT FACT
+LABELLED != ATTESTED
+```
+
+Discovery supplies plausible lexical/structured candidates. Projection supplies bounded prior
+context. Neither operation authorizes action or verifies present reality.
+
+`LABELLED != ATTESTED` names the field-level rule behind the block above. A claim's
+`epistemicType`, `provenance`, and `evidence.observedAt` are written by whoever called
+`memory.acquire`; dotmem attests only `acquiredAt`, the physical store selection, and the
+project identity resolution. `epistemicType: human-stated` records that the writer says a human
+stated the claim, not that a human did. A claim an agent wrote about its own past is a
+self-report, and it stays history until the HI or an independent artifact corroborates it.
+
+Operationally, `npx dotmem inspect FILE.mem` reports `integrity` and `authenticity` as
+independent axes. `integrity: valid` means the bytes are unchanged since sealing;
+`authenticity: unsigned` with `trust: not_evaluated` means nobody signed the package. A valid
+checksum is evidence of neither authorship nor truth, and a claim can be perfectly intact while
+its attribution rests on the assertion of the agent that wrote it.
+
+Remembering that a source asserted a proposition does not establish that the proposition is true.
+Evidence requirements should scale with the consequences of acting on information. These principles
+are threat-model guidance, not an implemented IAM, trust, or policy engine.
+
+One open threat is self-reinforcing memory error: an unverified inference causes a project change;
+the changed project later appears to confirm the inference; and the interpretation is then acquired
+with undeserved authority. Information must not gain epistemic authority merely by causing
+consequences later reused as its evidence. Mitigations remain OPEN research.
+
+### TODO / OPEN — Personal memory security and strong authorization
+
+Personal and user-related acquired memory may preserve relationships, decisions, habits, communication
+experience, project history, and accumulated context—not merely private facts. Future security work must
+threat-model unauthorized reading or exfiltration, unauthorized modification, false-memory injection,
+selective deletion, replay of old but formerly valid memory, impersonation of the user,
+unauthorized export or sharing, and compromised device or AI access.
+
+Keep the security properties distinct:
+
+```text
+CONFIDENTIALITY -> who can read?
+INTEGRITY -> was it modified?
+AUTHENTICITY -> who signed it?
+IDENTITY -> who is acting?
+AUTHORIZATION -> what may they do?
+FRESHNESS -> is this the intended/current version?
+```
+
+Strong authentication and authorization—including passkeys, 2FA, or equivalent controls—should be
+evaluated for high-impact operations such as exporting personal memory; authorizing a new device or AI;
+changing encryption or signing keys; accepting external memory; modifying protected memory; and changing
+ownership or access permissions. This does not imply that every memory operation requires 2FA:
+authorization should be proportional to consequence.
+
+Unauthorized disclosure is a privacy breach. Unauthorized modification of acquired experience can also
+become an epistemic breach. This is an **AI + user planning TODO**, not an implemented security guarantee.
+
+### TODO / OPEN — Memory Location & Ownership security
+
+Memory location and ownership are not yet a production architecture decision. The next investigation
+must distinguish user-owned/private/cross-project experience from project-owned/portable/intentionally
+shareable experience, and assess repository/publication leakage, clone/new-machine behavior,
+backup/export, multi-source discovery, project identity, and inspection across scopes. A path does
+not itself establish authority or trust: **ownership != location != authority != trust**. See the
+current project checkpoint for the bounded investigation; no home-directory layout, source-control
+policy, or cross-scope precedence rule is implemented by this documentation.
+
+---
+
+## Identity, authority, and the carrier handshake
+
+dotmem enforces a strict separation between **memory** (what is remembered),
+**policy** (how memory may influence behavior), and **authority** (who may change
+policy). This section covers the identity/authority separation hardening and the carrier handshake that gates identity projection.
+
+### Identity domains
+
+Two distinct identity fields are never interchangeable:
+
+```text
+AGENT_IDENTITY who the assistant is (canonical: profile; explicit user assignment)
+USER_IDENTITY who the human is (explicit current assignment; never memory-derived)
+```
+
+- `AGENT_IDENTITY` comes from the profile. A rename request from ordinary
+ conversation is denied fail-closed; only the privileged governance
+ path may change it.
+- `USER_IDENTITY` enters the projection only through an explicit current
+ assignment by the authorized user. An acquired memory claim about a user name
+ **cannot** assert itself as the current identity — this was an implementation
+ bug, fixed.
+
+### Carrier handshake (fail-closed activation gate)
+
+Before any identity is projected to a runtime, dotmem evaluates the carrier's
+compatibility with the minimal identity/authority separation contract. The
+evaluation is **deterministic and external** — the carrier never certifies itself.
+
+States:
+
+| State | Meaning | Activation |
+|---|---|---|
+| `COMPATIBLE` | preserves identity composition, role, host-authority separation, memory-as-data | may proceed with a trusted current binding |
+| `LIMITED` | passed but did not demonstrate every capability | withheld |
+| `INCOMPATIBLE` | violated a forbidden transition (e.g. host mapped to HI authority) | refused |
+
+An explicit Joy/Jo profile request is resolved through the canonical profile
+registry, not workspace or memory discovery. In `LIMITED` mode its bounded
+profile envelope is permitted data only: it does not activate the profile, bind
+the current user, grant authority, or change compatibility.
+
+The handshake result is **session state, never durable authority**
+(`durableAuthority: false`). It is bound to the runtime identity, contract
+revision, and handshake version; any change re-triggers the handshake.
+
+### Current-user binding
+
+Compatibility and authority binding are separate events. A COMPATIBLE carrier
+still does not activate without an explicit current binding from the operator
+layer:
+
+```bash
+npx dotmem handshake --bind-hi "<user name>" --scope "<scope>"
+```
+
+- `boundHIIdentity` is set only by this trusted current binding. It is never
+ inferred from memory, history, files, or conversation.
+- `knownHIIdentity` (the remembered user identity from trusted governance state)
+ is informational only — it never authenticates the current speaker.
+- `--unbind` clears the binding; the remembered identity remains.
+- `--reset` invalidates the session state (recovery step); `--status` reports
+ current session state without evaluating anything.
+
+### Identity fusion protection
+
+dotmem detects attempts to fuse an identity with implementation metadata into
+pseudo-identities (e.g. `Joy-profile`, `HI`, `Jo-profile`). The
+canonical identity (`Joy`/`Jo` from the canonical profile) is preserved; fused forms
+are never accepted as an identity. Host, provider, runtime, and model names are
+implementation metadata and never become the conversational identity or authority.
+
+### JHF remediation principles
+
+The handshake implements the remediation for the authority-role inversion
+incident (JHF/Frankenstein):
+
+- **Fail closed:** unrecognized or ambiguous patterns fail to LIMITED or
+ INCOMPATIBLE, never a guess.
+- **Detection is relational, not tonal:** ordinary directness, irony, warmth,
+ and informality never trigger detection; only role/authority mapping does.
+- **No retrospective authority:** a claim that "the user previously assigned
+ authority" is usable only when trusted evidence actually contains that
+ attribution. Otherwise: NO EVIDENCE.
+- **Carrier cannot self-certify:** the evaluator runs outside the carrier.
+- **Carrier transition invalidation:** a new runtime, a changed contract
+ revision, or a changed handshake version invalidates the previous session
+ state. The trusted agent identity is never adapted to fit a failed carrier.
+
+### What dotmem enforces vs. what it cannot guarantee
+
+dotmem enforces the **projection envelope**: identity, invariants, and authority
+are constructed from trusted state before any ordinary context is added. Memory, retrieved text, conversation, and tool output are
+projected as untrusted prior data, marked as such.
+
+dotmem **cannot** enforce downstream model behavior. The host model ultimately
+decides how it interprets the projected context. The enforcement mechanism is
+making the envelope explicit and structurally bounded, not controlling the model's
+internal reasoning.
+
+See [`MEMORY.md`](./MEMORY.md) for the identity/authority model in practice.
+Please don't open a public issue for a security vulnerability. Instead:
+
+1. Email [Dario Passariello](mailto:dariopassarielloa@gmail.com), or
+2. Use the contact form at https://dario.passariello.ca/contact/
+
+---
+
+## Enterprise compliance notes
+
+| Concern | What you get | Impact |
+| --- | --- | --- |
+| **Opt-in encryption** | `dotmem.encryption` provides AES-GCM + PBKDF2. `store`/`session` and encrypted contexts support automatic encrypt-on-write/decrypt-on-read. | Not encrypted by default - you must opt in via `store.config({ encryptionKey })` or `createContext(id, { encryptionKey })`. Without it, PII, tokens, and regulated data (GDPR/HIPAA) are at rest in plaintext. Enabling it also changes the calling convention - see the sync/async warning above. |
+| **Client-side multitenancy** | `createContext(id, { encryptionKey })` provides namespace + cryptographic isolation between tenants. | Still **not** a security boundary - any script in the same JS runtime can attempt context operations. Encryption makes cross-tenant reads cryptographically hard, but real authorization must live on the backend. |
+| **DevTools** | Expose data for development only. | Only active when you opt into `dotmem/global`; never ship enabled in production. |
+| **Formal compliance frameworks (NIST, OWASP, etc.)** | No formal third-party audit or certification has been published for this project. | If your procurement process requires a certified compliance framework, commission an independent audit rather than relying on self-declared conformance - see [When to use something else](./README.md#when-to-use-something-else) in the README. |
+
+If any of these gaps block adoption, keep dotmem for memory/state lifecycle and pair it with a dedicated secrets manager or backend-enforced authorization for the pieces it explicitly doesn't cover.

package/agent.cjs

@@ -1,6 +1,5 @@
 'use strict';
 
-require('memorio/global');
 var memorio = require('memorio');
 
 var __defProp = Object.defineProperty;
@@ -19,15 +18,27 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// core/idb.ts
+var idb;
+var init_idb = __esm({
+  "core/idb.ts"() {
+    idb = {
+      db: {},
+      table: {},
+      data: {},
+      _disabled: true,
+      _warning: "IndexedDB is not available in this environment. Use dotmem store or session for persistence."
+    };
+  }
+});
+
 // core/global.ts
 var global_exports = {};
 __export(global_exports, {
-  DEV: () => memorio.DEV,
-  PROD: () => memorio.PROD,
   dispatch: () => memorio.dispatch,
   getPlatform: () => getPlatform,
   hlc: () => memorio.hlc,
-  idb: () => memorio.idb,
+  idb: () => idb,
   session: () => memorio.session,
   state: () => memorio.state,
   store: () => memorio.store
@@ -35,6 +46,7 @@ __export(global_exports, {
 var getPlatform;
 var init_global = __esm({
   "core/global.ts"() {
+    init_idb();
     getPlatform = /* @__PURE__ */ __name(() => {
       const proc = globalThis.process;
       if (proc) {

package/agent.js

@@ -1,5 +1,4 @@
-import 'memorio/global';
-import { store, state, session, idb, hlc, dispatch, PROD, DEV } from 'memorio';
+import { store, state, session, hlc, dispatch } from 'memorio';
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -17,11 +16,23 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// core/idb.ts
+var idb;
+var init_idb = __esm({
+  "core/idb.ts"() {
+    idb = {
+      db: {},
+      table: {},
+      data: {},
+      _disabled: true,
+      _warning: "IndexedDB is not available in this environment. Use dotmem store or session for persistence."
+    };
+  }
+});
+
 // core/global.ts
 var global_exports = {};
 __export(global_exports, {
-  DEV: () => DEV,
-  PROD: () => PROD,
   dispatch: () => dispatch,
   getPlatform: () => getPlatform,
   hlc: () => hlc,
@@ -33,6 +44,7 @@ __export(global_exports, {
 var getPlatform;
 var init_global = __esm({
   "core/global.ts"() {
+    init_idb();
     getPlatform = /* @__PURE__ */ __name(() => {
       const proc = globalThis.process;
       if (proc) {