@gnolith/taproot 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.3.0
+
+- **Breaking 0.3 API:** removed `TaprootRepository`, `createTaproot`, and every
+  unscoped canonical read helper from the normal package export. Canonical
+  entity, history, list, term-search, audit, export, integrity, and repair
+  access now exists only through mandatory `AuthorizedTaprootReader` context.
+- Added host-issued non-extractable AES-GCM cursor capability, authenticated
+  cursors bound to caller/grants/query/filter/auth revision/data generation,
+  fixed-size plaintext padding, identifier-only candidate scans, denied-heavy
+  page filling, and final authorization rechecks. Revision and audit generation
+  invalidate cursors after writes and repair. Stale, tampered, and cross-context
+  cursors fail generically.
+- Public mutation helpers now return minimal receipts and reject validator/RDF
+  factory callbacks and configurable entity-size probes, so write configuration
+  cannot observe preexisting canonical content. They require a process-local
+  opaque installation authorization guard bound to the exact database object
+  and installation base IRI. Normal writes require current `knowledge:write`;
+  policy changes require orthogonal `knowledge:policy`. Raw repository
+  internals are not package-exported.
+- Added host-created authorization contexts, canonical CNF visibility scopes,
+  lossless scope intersection, portable fingerprints, explicit `search:admin`
+  checks, and fail-closed pre/post-hydration canonical reads.
+- Added checksummed migration 4 with immutable installation authorization
+  state, current and per-revision entity/statement policy, atomic projection
+  outbox and counter advances, fail-closed legacy quarantine, and bounded
+  hash-attested `search:admin` backfill. Unique durable advance IDs prevent
+  same-target ABA races for canonical and cross-package ordered batches.
+- Runtime JavaScript writes now fail closed when authorization metadata is
+  omitted, authorize before loading existing canonical state, validate redirect
+  targets and historical reverts against current policy, and preserve generic
+  denial behavior for missing, stale, or inaccessible targets.
+- Cross-package authorization fencing is guard-executed and inseparable from
+  the ordered database batch. Authorization singleton/audit rows reject
+  replacement, readiness verifies current and historical statement-policy
+  coverage, and authorized bulk import advances its context between entities.
+- Added host-issued fence-only domain guards bound to one exact non-Knowledge
+  capability. Task/Memory-style writes can share the installation revision
+  without borrowing Knowledge authority or advancing counters; Knowledge
+  advances require orthogonal policy authority and bind the prior durable
+  advance ID.
+- Authorization readiness and persisted sources now require exact parity
+  between mutable current policy and its immutable matching revision, and
+  recompute historical statement coverage/effective visibility before use.
+  Operational inspection also validates exact trigger definitions.
+
+- Added required, explicitly authored nonblank `Statement.text` to canonical
+  JSON and to every logical statement mutation.
+- Added canonical JSON migration 3. Existing databases with no unauthored
+  statements upgrade atomically; persisted statements without text fail closed
+  rather than receiving inferred fallback prose.
+- Whole-entity replacement and historical revert now require an exact
+  statement-ID-to-text resupply map, preventing silent stale-text carry.
+
 ## 0.2.0
 
 - Added a runtime-neutral SQLite persistence surface while retaining D1

package/COMPATIBILITY.md

@@ -1,6 +1,6 @@
 # Wikibase compatibility target
 
-Taproot 0.2.x requires `@gnolith/diamond` 0.4.0 exactly. Existing Cloudflare D1
+Taproot 0.3.x requires `@gnolith/diamond` 0.4.0 exactly. Existing Cloudflare D1
 objects remain compatible with the exported `D1DatabaseLike` surface. New
 embedders may use the equivalent `SqliteDatabaseLike`; both require one
 adapter/connection with ordered atomic batch semantics.
@@ -25,8 +25,10 @@ Intentional differences:
   lifecycle RDF; deleted content remains available in immutable revisions.
 - Search is a deterministic D1 term projection using case-insensitive
   substring matching. FTS5 is not required.
-- Taproot stores attribution claims but does not authenticate them. Identity
-  verification, authorization, and agent/MCP transport remain host concerns.
+- Taproot stores attribution claims but does not authenticate them. Normal
+  canonical reads require a host-created authorization context and use
+  Taproot's persisted canonical policy. Authentication, principals,
+  memberships, sessions, and agent/MCP transport remain host concerns.
 - The compatibility target is Wikibase core Items and Properties. Lexemes,
   Forms, Senses, EntitySchemas, MediaInfo, MediaWiki page metadata, and
   normalized external-ID formatter URLs are not claimed as supported entity

package/README.md

@@ -12,7 +12,7 @@ editing commands, term search, repairable projections, and a deterministic RDF p
 
 ## Status
 
-Version `0.2.0` supports Node 22 and 24 and depends exactly on Diamond `0.4.0`,
+Version `0.3.0` supports Node 22 and 24 and depends exactly on Diamond `0.4.0`,
 which exposes transaction-composable RDF patches, a runtime-neutral SQLite
 capability, and a process-local `node:sqlite` adapter.
 
@@ -21,6 +21,8 @@ capability, and a process-local `node:sqlite` adapter.
 - Items and Properties with Wikibase-style canonical JSON.
 - Labels, descriptions, aliases, sitelinks, statements, qualifiers,
   references, ranks, and all three snak types.
+- Nonblank, explicitly authored text for every logical statement revision;
+  Taproot never generates prose from properties or values.
 - Item, Property, Lexeme, Form, Sense, and EntitySchema links; string,
   external ID, URL, Commons media, monolingual text, time,
   quantity, coordinate, math, musical notation, geo-shape, and tabular-data
@@ -46,25 +48,57 @@ tables idempotently. First initialization requires the database's permanent
 identity:
 
 ```ts
-import { TaprootRepository, initializeTaproot } from '@gnolith/taproot';
+import {
+  createAuthorizationCursorCodec,
+  createAuthorizedTaproot,
+  createItem,
+  bootstrapTaprootAuthorization,
+  createInstallationAuthorizationGuard,
+  createTaprootHostWriteCapability,
+  initializeTaproot,
+  setLabel,
+} from '@gnolith/taproot';
 
 await initializeTaproot(env.DB, { baseIri: 'https://knowledge.example' });
-const knowledge = new TaprootRepository(env.DB, {
+const options = {
   baseIri: 'https://knowledge.example',
+};
+const writeCapability = createTaprootHostWriteCapability(
+  env.DB,
+  options,
+  nonExtractableHmacSha256Key,
+);
+await bootstrapTaprootAuthorization(
+  env.DB,
+  options,
+  writeCapability,
+  'installation-1',
+);
+const guard = await createInstallationAuthorizationGuard(
+  env.DB,
+  options,
+  writeCapability,
+);
+
+const item = await createItem(env.DB, options, guard, writeContext, {
+  labels: { en: { language: 'en', value: 'Ada Lovelace' } },
+  authorization: canonicalPolicy,
 });
 
-const property = await knowledge.createProperty({
-  datatype: 'string',
-  labels: { en: { language: 'en', value: 'occupation' } },
-});
-const item = await knowledge.createItem({
-  labels: { en: { language: 'en', value: 'Ada Lovelace' } },
+// The host derives context only from authenticated state. Taproot loads its
+// persisted canonical policy itself. The cursor key is durable and host-held.
+const knowledge = createAuthorizedTaproot(env.DB, options, readContext, {
+  cursorCodec: createAuthorizationCursorCodec(nonExtractableAesGcmKey),
 });
+const canonical = await knowledge.getEntity(item.entityId);
 ```
 
+Never accept either host key, host capability, authorization guard, context, or
+policy from a request, MCP argument, prompt, or query.
+
 Use Taproot's `planTaprootMigrations`, `applyTaprootMigrations`, and
 `initializeTaproot` APIs for schema changes. The numbered SQL files document
-the historical 0.1 layout and are not an operator migration interface in 0.2.
+the historical 0.1 layout and are not an operator migration interface in 0.3.
 The package APIs own checksums, conservative adoption, application-level
 SHA-256 backfills, and RDF reprojection.
 
@@ -78,35 +112,72 @@ Diamond patch together. A stale guard or any SQL/RDF failure rolls the whole
 batch back.
 
 ```ts
-const edited = await knowledge.setLabel(item.entityId, 'fr', 'Ada Lovelace', {
-  expectedRevision: item.newRevision,
-  attribution: {
-    id: 'agent:cataloguer',
-    kind: 'agent',
-    tool: 'gnolith-mcp',
+const edited = await setLabel(
+  env.DB,
+  options,
+  guard,
+  currentWriteContext,
+  item.entityId,
+  'fr',
+  'Ada Lovelace',
+  {
+    expectedRevision: item.newRevision,
+    attribution: {
+      id: 'agent:cataloguer',
+      kind: 'agent',
+      tool: 'gnolith-mcp',
+    },
+    editSummary: 'add French label',
+    tags: ['agent'],
+    requestId: 'mcp-request-123',
+    authorization: currentCanonicalPolicy,
   },
-  editSummary: 'add French label',
-  tags: ['agent'],
-  requestId: 'mcp-request-123',
-});
+);
 ```
 
-The public API includes reads/search; create/import/replace; soft delete,
-restore, and redirect; all term/sitelink commands; complete statement,
-qualifier, reference, and rank commands; audit/history and integrity reads;
-bulk workflows; and canonical JSON parse, validate, create, and export helpers. Top-level function forms are exported alongside
-`TaprootRepository`.
-
-Set `requireAttribution: true` to reject unattributed writes. `validators`
-provide host policy checks without coupling Taproot to authentication, and
-`observe` receives isolated success/error timing records for committed writes.
+The public API exposes canonical reads only on `AuthorizedTaprootReader`.
+Entity/history/list/term-search/audit/export and integrity operations require a
+host-created authorization context and Taproot's persisted policy source.
+Public mutation helpers require the DB/installation-bound opaque authorization
+guard, a current context with exact `knowledge:write`, and canonical policy
+input. Policy changes additionally require exact `knowledge:policy`. They
+return only entity ID, previous/new revision, authorization/search generation,
+and committed status;
+they do not return canonical JSON, text, RDF counts, hashes, or audit bodies.
+`TaprootRepository` and raw read helpers are intentionally absent from package
+exports in the breaking 0.3 line.
+
+The opaque guard also owns execution of ordered cross-package batches that
+need an exact authorization-revision fence or advance. It does not expose raw
+counter-update statements that a caller could separate from the corresponding
+audit, assertion, or domain writes.
+Hosts issue a distinct fence-only domain guard for each exact non-Knowledge
+domain capability, such as Task or Memory writes. The capability is bound at
+issuance, cannot be supplied at the call site, and an ordinary domain fence
+does not advance authorization or search counters. Knowledge authorization
+advances additionally require `knowledge:policy`.
+
+Statement creation and replacement include `text` on the `Statement` itself.
+Rank, qualifier, and reference mutation methods require authored text for the
+new logical statement revision. `replaceEntity` and `revertEntity` require an
+exact `statementTexts` map for every statement they carry forward. Reusing old
+wording is allowed only when the caller deliberately supplies it again.
+
+Set `requireAttribution: true` to reject unattributed writes. `observe` receives
+isolated success/error timing records. Public write options cannot install
+validators or RDF factories over canonical state and cannot vary the canonical
+entity-size limit; hosts perform domain validation before invoking the write
+using separately authorized input.
 
 ## SPARQL prefixes
 
 `wikibasePrefixes(baseIri)` returns site-owned `wd:`, `wds:`, `wdv:`,
 `wdref:`, `wdt:`, `p:`, `ps:`, `psv:`, `pq:`, `pqv:`, `pr:`, `prv:`, and
-`wdno:` namespaces. Pass the D1 binding to Diamond's read-only SPARQL handler
-to query them.
+`wdno:` namespaces. Diamond's database-level SPARQL handler can query them, but
+it sees the complete graph and is privileged host maintenance/debug
+infrastructure. Do not expose it to a user, agent, MCP, or search caller.
+Normal SPARQL needs an authorization-scoped dataset and final canonical policy
+recheck in the owning host.
 
 ## Limits
 
@@ -116,8 +187,10 @@ that as `QuadPatchTooLargeError`. Store PDFs, images, audio, OCR, transcripts,
 and article bodies externally and represent them as knowledge Items.
 
 Bulk imports default to create-only, can opt into `upsert`, are capped at 100
-entities by default, and commit one entity atomically at a time. Multi-command
-edits apply up to 100 commands in one revision. All list limits are capped at 500.
+entities by default, and commit one entity atomically at a time. Authorized
+bulk policies use sequential expected authorization revisions; Taproot carries
+each successful advance into the next entity's context. Multi-command edits
+apply up to 100 commands in one revision. All list limits are capped at 500.
 
 See the [local D1 and Diamond interoperability example](examples/d1-diamond-interop/README.md),
 [`COMPATIBILITY.md`](COMPATIBILITY.md), and the architecture, API, operations,

package/SECURITY.md

@@ -11,9 +11,12 @@ canonical history or RDF query results, and whether untrusted JSON or SPARQL
 input is required. Do not include production data or credentials.
 
 Taproot records attribution claims but does not authenticate identities or
-authorize writes. It assumes mutation routes admit trusted callers. Canonical JSON,
-revision/audit immutability, size limits, optimistic revision guards, and
-read-only Diamond SPARQL are security boundaries; projection tables are not.
+persist principals, memberships, or sessions. It does persist canonical entity
+authorization policy and requires a host-created current context plus an
+opaque DB-bound guard for normal writes. Canonical JSON, authorization policy,
+revision/audit immutability, size limits, optimistic revision/authorization
+guards, and read-only Diamond SPARQL are security boundaries; rebuildable
+projection content is not authoritative.
 
 The threat model and host responsibilities are documented in
 `docs/threat-model.md`.

package/dist/authorization-maintenance.d.ts

@@ -0,0 +1,55 @@
+import type { SqliteDatabaseLike } from '@gnolith/diamond';
+import type { EntityId, VisibilityScopeV1, AuthorizationContext } from './types.js';
+export type AuthorizationReadinessCode = 'missing-current-policy' | 'current-revision-mismatch' | 'cross-installation-policy' | 'authorization-revision-invalid' | 'entity-policy-mismatch' | 'missing-revision-policy' | 'statement-policy-mismatch';
+export interface AuthorizationReadinessIssue {
+    entityId: EntityId;
+    currentRevision: number;
+    codes: AuthorizationReadinessCode[];
+}
+export interface AuthorizationReadinessInspection {
+    installationId: string;
+    authorizationRevision: number;
+    searchGeneration: number;
+    counts: {
+        canonicalEntities: number;
+        canonicalRevisions: number;
+        currentPolicies: number;
+        revisionPolicies: number;
+        quarantinedEntities: number;
+        revisionPolicyMismatches: number;
+        entityPolicyMismatches: number;
+        statementPolicyMismatches: number;
+        currentHistoryParityMismatches: number;
+    };
+    ready: boolean;
+    issues: AuthorizationReadinessIssue[];
+    cursor: EntityId | null;
+}
+export interface AuthorizationBackfillRevisionInput {
+    revision: number;
+    contentHash: string;
+    workspaceId: string | null;
+    ownerPrincipalId: string;
+    visibility: VisibilityScopeV1;
+    statementRestrictions: Readonly<Record<string, readonly VisibilityScopeV1[]>>;
+}
+export interface AuthorizationBackfillEntityInput {
+    entityId: EntityId;
+    revisions: readonly AuthorizationBackfillRevisionInput[];
+}
+export interface AuthorizationBackfillPlan {
+    planId: string;
+    installationId: string;
+    baseAuthorizationRevision: number;
+    manifestHash: string;
+    entityCount: number;
+    revisionCount: number;
+    status: 'planned' | 'complete';
+}
+export declare function inspectAuthorizationReadiness(db: SqliteDatabaseLike, rawContext: AuthorizationContext, options?: {
+    limit?: number;
+    cursor?: EntityId;
+}): Promise<AuthorizationReadinessInspection>;
+export declare function planAuthorizationBackfill(db: SqliteDatabaseLike, rawContext: AuthorizationContext, inputs: readonly AuthorizationBackfillEntityInput[], now?: string): Promise<AuthorizationBackfillPlan>;
+export declare function applyAuthorizationBackfill(db: SqliteDatabaseLike, rawContext: AuthorizationContext, planId: string, now?: string): Promise<AuthorizationBackfillPlan>;
+//# sourceMappingURL=authorization-maintenance.d.ts.map

package/dist/authorization-maintenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-maintenance.d.ts","sourceRoot":"","sources":["../src/authorization-maintenance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAc1B,OAAO,KAAK,EACV,QAAQ,EACR,iBAAiB,EAEjB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAOpB,MAAM,MAAM,0BAA0B,GAClC,wBAAwB,GACxB,2BAA2B,GAC3B,2BAA2B,GAC3B,gCAAgC,GAChC,wBAAwB,GACxB,yBAAyB,GACzB,2BAA2B,CAAC;AAEhC,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,EAAE,0BAA0B,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,gCAAgC;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE;QACN,iBAAiB,EAAE,MAAM,CAAC;QAC1B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;QACzB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,wBAAwB,EAAE,MAAM,CAAC;QACjC,sBAAsB,EAAE,MAAM,CAAC;QAC/B,yBAAyB,EAAE,MAAM,CAAC;QAClC,8BAA8B,EAAE,MAAM,CAAC;KACxC,CAAC;IACF,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,2BAA2B,EAAE,CAAC;IACtC,MAAM,EAAE,QAAQ,GAAG,IAAI,CAAC;CACzB;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,kCAAkC,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,yBAAyB,EAAE,MAAM,CAAC;IAClC,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,SAAS,GAAG,UAAU,CAAC;CAChC;AAoCD,wBAAsB,6BAA6B,CACjD,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;CAAO,GAClD,OAAO,CAAC,gCAAgC,CAAC,CAoK3C;AA4JD,wBAAsB,yBAAyB,CAC7C,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,SAAS,gCAAgC,EAAE,EACnD,GAAG,GAAE,MAAiC,GACrC,OAAO,CAAC,yBAAyB,CAAC,CA8KpC;AAED,wBAAsB,0BAA0B,CAC9C,EAAE,EAAE,kBAAkB,EACtB,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,MAAiC,GACrC,OAAO,CAAC,yBAAyB,CAAC,CA+OpC"}