@githolon/dsl 0.49.0 → 0.51.0

package/check_package.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// NOMOS — Nomos Sovereign: participants act · verify · remember LOCALLY; hosted
+// remotes are replaceable custody/transport, not truth.  ⇒ ONE Nomos GitHolon
+// wasm32-wasip1 artifact {kernel · projection · embedded QuickJS engine}.
+// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
+
+// `githolon check` launcher — the twin of `compile_package.mjs`: resolve `tsx`
+// (the caller's, else the DSL's own dependency) and run `src/check_package_main.ts`
+// under it (the main dynamically imports the caller's TS domain modules, which
+// needs the tsx ESM loader). Resolution goes through Node's resolver (createRequire),
+// NOT node_modules/.bin paths — hoisted/workspace installs put the bin shims elsewhere.
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const DSL_DIR = path.dirname(fileURLToPath(import.meta.url));
+const MAIN = path.join(DSL_DIR, "src", "check_package_main.ts");
+
+function resolvePkgDir(name, fromDir) {
+  try {
+    const req = createRequire(pathToFileURL(path.join(fromDir, "noop.js")));
+    return path.dirname(req.resolve(`${name}/package.json`));
+  } catch {
+    return undefined;
+  }
+}
+
+const tsxDir = resolvePkgDir("tsx", process.cwd()) ?? resolvePkgDir("tsx", DSL_DIR);
+if (!tsxDir) {
+  console.error("githolon check: tsx not found — reinstall @githolon/dsl (tsx is one of its dependencies)");
+  process.exit(1);
+}
+const tsxPkg = JSON.parse(readFileSync(path.join(tsxDir, "package.json"), "utf8"));
+const tsxBinRel = typeof tsxPkg.bin === "string" ? tsxPkg.bin : tsxPkg.bin?.tsx;
+const tsxCli = path.join(tsxDir, tsxBinRel ?? "dist/cli.mjs");
+
+try {
+  execFileSync(process.execPath, [tsxCli, MAIN, ...process.argv.slice(2)], {
+    stdio: "inherit",
+    cwd: process.cwd(),
+  });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/dart/example/nomos_secure_key_store.dart

@@ -0,0 +1,82 @@
+// COPY THIS INTO YOUR FLUTTER APP. It is an EXAMPLE, not part of the `nomos_client` library: it depends on
+// `flutter_secure_storage`, which the pure-Dart `nomos_client` package deliberately does NOT depend on (so
+// the protocol logic stays Flutter-free and unit-testable). This is the ~40 lines of app-specific glue for
+// where your device secret lives — the E2E key CUSTODY policy is yours; the protocol plumbing is not.
+//
+// THE SEALING CLIENT (e2e_sealing_client.md): a generated `<Domain>Client(bridge, keyStore: ...)` seals
+// encrypted directive fields before dispatch + decrypts encrypted read fields automatically. The `keyStore`
+// is the ONE thing you supply. `WrappedKeyStore` (in `nomos_client`) is the default: it unwraps this
+// principal's on-chain WrappedKeys with a DEVICE SECRET. This example shows where that device secret lives —
+// the platform keychain / Keystore via `flutter_secure_storage` — so it survives app restarts, stays off the
+// chain, and never leaves the device.
+//
+// WIRING (once per signed-in principal):
+//   final store = await SecureDeviceKeyStore.open(bridge: bridge, principal: myUid);
+//   final app = NotesClient(bridge, actor: myUid, keyStore: store);   // reads decrypt, writes seal
+//   final rows = await app.notesByOwner(owner: myUid);                // `body` comes back plaintext
+//
+// The OWNER ceremony (grantAndWrap / revokeAndRotate / rotate) uses the SAME device pubkey this store
+// publishes — see `<Domain>Client(bridge, actor: owner).encryption`.
+
+import 'dart:convert';
+
+import 'package:flutter_secure_storage/flutter_secure_storage.dart';
+import 'package:nomos_client/nomos_client.dart';
+
+/// A [NomosKeyStore] whose device secret is held in the platform keychain (iOS Keychain / Android Keystore)
+/// via `flutter_secure_storage`. It delegates the scope-key unwrap to the framework's [WrappedKeyStore]; the
+/// only thing it adds is DURABLE, PLATFORM-PROTECTED custody of the X25519 device secret.
+class SecureDeviceKeyStore implements NomosKeyStore {
+  final WrappedKeyStore _inner;
+
+  /// This device's X25519 PUBLIC key — publish it (publishEncKey) / hand it to the owner as `publicKey` on
+  /// `grantAndWrap` so the scope key can be wrapped TO this device.
+  final String devicePublicKey;
+
+  SecureDeviceKeyStore._(this._inner, this.devicePublicKey);
+
+  /// Open (or first-time provision) the store for `principal`. On first run it MINTS an X25519 device keypair
+  /// in the kernel, persists the SECRET in secure storage, and returns the store; on later runs it reuses it.
+  static Future<SecureDeviceKeyStore> open({
+    required NomosBridge bridge,
+    required String principal,
+    FlutterSecureStorage storage = const FlutterSecureStorage(),
+  }) async {
+    final secretKey = 'nomos.enc.deviceSecret.$principal';
+    final publicKey = 'nomos.enc.devicePublic.$principal';
+    var secret = await storage.read(key: secretKey);
+    var public = await storage.read(key: publicKey);
+    if (secret == null || public == null) {
+      // FIRST RUN: mint the device keypair (secret stays client-side, never on chain) and persist it.
+      final kp = await bridge.cryptoKeygen();
+      secret = (kp['secret'] ?? '').toString();
+      public = (kp['public'] ?? '').toString();
+      await storage.write(key: secretKey, value: secret);
+      await storage.write(key: publicKey, value: public);
+    }
+    final inner = WrappedKeyStore(
+        bridge: bridge, principal: principal, deviceSecret: secret);
+    return SecureDeviceKeyStore._(inner, public);
+  }
+
+  @override
+  Future<NomosScopeKey?> scopeKey(String scope) => _inner.scopeKey(scope);
+
+  @override
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes) =>
+      _inner.readKeys(scopes);
+
+  /// Convenience: the JSON a `publishEncKey` payload carries (bind the device pubkey to this principal on
+  /// chain so an owner's `grantAndWrap` can resolve it without you passing `publicKey` each time).
+  Map<String, Object?> publishPayload({required String publishedAt}) => {
+        'principal': _inner.principal,
+        'encPublicKey': devicePublicKey,
+        'publishedAt': publishedAt,
+      };
+
+  @override
+  String toString() => 'SecureDeviceKeyStore(${jsonEncode({
+        'principal': _inner.principal,
+        'devicePublicKey': devicePublicKey,
+      })})';
+}

package/dart/lib/src/webview_bridge.dart

@@ -15,6 +15,7 @@
 library;
 
 import 'dart:async';
+import 'dart:convert';
 import 'dart:math';
 
 import 'errors.dart' show nomosErrorFromInfo;
@@ -292,6 +293,377 @@ class NomosBbox {
       {'minLng': minLng, 'minLat': minLat, 'maxLng': maxLng, 'maxLat': maxLat};
 }
 
+// ── E2E SEALING (the sealing client) — the GENERIC key-custody surface. Generated domain clients bake the
+//   per-domain map + seal/read helpers, but these types are domain-agnostic, so they live here (in the
+//   nomos_client library) exactly like [MissingOfferAuthority] — one definition, re-exported per client. ──
+
+/// A held E2E scope key: the base64 symmetric key + the epoch it belongs to (forward-only rotation).
+class NomosScopeKey {
+  final String scope;
+  final int epoch;
+  final String key;
+  const NomosScopeKey(
+      {required this.scope, required this.epoch, required this.key});
+  Map<String, Object?> toJson() => {'scope': scope, 'epoch': epoch, 'key': key};
+}
+
+/// The app-supplied KEY CUSTODY surface (E2E sealing). Supply one to a generated `<Domain>Client` and its
+/// encrypted directive fields SEAL automatically before dispatch + encrypted read fields DECRYPT
+/// automatically. [WrappedKeyStore] is the default over the on-chain WrappedKeys; an app may implement this
+/// to source keys from secure storage (the key custody policy stays the app's; the protocol plumbing does not).
+abstract class NomosKeyStore {
+  /// The CURRENT (highest-epoch) scope key, for SEALING a write. null ⇒ EncryptionKeyUnavailable.
+  Future<NomosScopeKey?> scopeKey(String scope);
+
+  /// EVERY held key for these scopes (all epochs), injected on reads so old ciphertext also decrypts.
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes);
+}
+
+/// Thrown when a write must seal an encrypted field but the KeyStore holds no key for its scope — the write
+/// NEVER falls through to a plaintext dispatch (the sid-envelope gate would refuse it anyway; we pre-fire).
+class EncryptionKeyUnavailable implements Exception {
+  final String scope;
+  final String field;
+  String get code => 'nomos.crypto.key_unavailable';
+  String get recommendedAction => 'obtainScopeKey';
+  EncryptionKeyUnavailable(this.scope, this.field);
+  @override
+  String toString() =>
+      'EncryptionKeyUnavailable: cannot seal "$field": no scope key held for "$scope" (obtain the cap + wrap the scope epoch first)';
+}
+
+/// THE DEFAULT KeyStore — unwraps this principal's on-chain WrappedKeys with its device secret, caching per
+/// scope. Mirror of the documented reader handshake (e2e_encryption.md): the secret stays client-side, the
+/// operator stays blind. Key custody (where `deviceSecret` lives — enclave, password-derived, …) is the app's.
+class WrappedKeyStore implements NomosKeyStore {
+  final NomosBridge bridge;
+  final String principal;
+  final String deviceSecret;
+  final Map<String, Future<List<NomosScopeKey>>> _cache = {};
+  WrappedKeyStore(
+      {required this.bridge,
+      required this.principal,
+      required this.deviceSecret});
+
+  Future<List<NomosScopeKey>> _loadScope(String scope) {
+    return _cache.putIfAbsent(scope, () async {
+      final rows = await bridge
+          .query('wrappedKeysByRecipient', {'recipientPrincipal': principal});
+      final held = <NomosScopeKey>[];
+      for (final row in rows) {
+        final d = ((row['data'] ?? row) as Map);
+        if (d['scope']?.toString() != scope) continue;
+        final key = await bridge.cryptoUnwrapKey(
+            secret: deviceSecret,
+            hpkeEpk: d['hpkeEpk'].toString(),
+            ct: d['ct'].toString());
+        held.add(NomosScopeKey(
+            scope: scope,
+            epoch: (d['epoch'] as num?)?.toInt() ?? 0,
+            key: key));
+      }
+      held.sort((a, b) => b.epoch - a.epoch);
+      return held;
+    });
+  }
+
+  @override
+  Future<NomosScopeKey?> scopeKey(String scope) async {
+    final ks = await _loadScope(scope);
+    return ks.isEmpty ? null : ks.first;
+  }
+
+  @override
+  Future<List<NomosScopeKey>> readKeys(List<String> scopes) async {
+    final all = <NomosScopeKey>[];
+    for (final s in scopes) {
+      all.addAll(await _loadScope(s));
+    }
+    return all;
+  }
+}
+
+// ── E2E OWNER CEREMONY (the sealing client, slice 2) — the owner-side twin of [WrappedKeyStore]. Domain-
+//   agnostic, so it lives here (re-exported per client) exactly like the KeyStore. It composes the framework
+//   key-epoch fan-out (`advanceKeyEpoch`, dispatched by its REAL id) with the domain's own grant/revoke
+//   directive, resolving the roster + each member's wrap-target pubkey FROM THE CHAIN — so the operator-blind
+//   handshake (grant → advance epoch → wrap to every member) is ONE call. Mirror of the TS `_ownerEncryption`. ──
+
+/// Thrown by the owner ceremony when a roster member has NO wrap-target key (no publishEncKey on chain, no
+/// prior wrap, no supplied override) — the ceremony NEVER wraps to a default (fail-closed; a keyless member
+/// is "not yet a member", per e2e_encryption.md's FOOTGUNS).
+class EncryptionMemberKeyMissing implements Exception {
+  final String principal;
+  final String scope;
+  String get code => 'nomos.crypto.member_key_missing';
+  String get recommendedAction => 'publishEncKey';
+  EncryptionMemberKeyMissing(this.principal, this.scope);
+  @override
+  String toString() =>
+      'EncryptionMemberKeyMissing: cannot wrap the "$scope" scope key to member "$principal" — no encryption public key on chain (publishEncKey) and none supplied (fail-closed)';
+}
+
+/// Thrown when the resolved roster != the caller's declared `expectRoster` BEFORE dispatch — pre-firing the
+/// kernel fan-out gate (wrap set == roster) so a rotation against a stale roster view never spends an epoch.
+class EncryptionRosterMismatch implements Exception {
+  final String scope;
+  final List<String> missing;
+  final List<String> extra;
+  String get code => 'nomos.crypto.roster_mismatch';
+  String get recommendedAction => 'reconcileRoster';
+  EncryptionRosterMismatch(this.scope, this.missing, this.extra);
+  @override
+  String toString() =>
+      'EncryptionRosterMismatch: roster for "$scope" != expected (the fan-out gate would refuse): missing $missing, unexpected $extra';
+}
+
+/// The outcome of an epoch-advancing ceremony verb: the new local [head], the [epoch] opened, and the
+/// [roster] the key was wrapped to.
+class NomosEpochResult {
+  final String head;
+  final int epoch;
+  final List<String> roster;
+  const NomosEpochResult(
+      {required this.head, required this.epoch, required this.roster});
+}
+
+/// THE OWNER CEREMONY surface — `<Domain>Client(bridge, actor: owner).encryption`. All three verbs open a
+/// FRESH epoch (a fresh 32-byte secret) and fan the wraps to the resolved roster; the membership change (if
+/// any) is the domain grant/revoke dispatched first, in the same call.
+class NomosEncryption {
+  final NomosBridge bridge;
+  final String domain;
+  final String? domainHash;
+  final String? actor;
+
+  /// The encryption scopes this domain defines (each a `requires(cap)`).
+  final List<String> scopes;
+
+  NomosEncryption(
+      {required this.bridge,
+      required this.domain,
+      this.domainHash,
+      this.actor,
+      required this.scopes});
+
+  String _defScope([String? scope]) {
+    if (scope != null && scope.isNotEmpty) return scope;
+    if (scopes.length == 1) return scopes.first;
+    throw StateError(
+        'this domain defines ${scopes.length} encryption scopes $scopes — pass a scope to pick one');
+  }
+
+  // A BARE scope IS `workspace:self#<relation>` (the era rule); a per-record scope is `<type>:<id>#<relation>`.
+  ({String object, String relation}) _parseScope(String scope) {
+    final h = scope.indexOf('#');
+    return h < 0
+        ? (object: 'workspace:self', relation: scope)
+        : (object: scope.substring(0, h), relation: scope.substring(h + 1));
+  }
+
+  /// The CURRENT roster of a scope (active direct-grant members, principal-form). Defaults to the sole scope.
+  Future<List<String>> roster([String? scope]) => _readRoster(_defScope(scope));
+
+  Future<List<String>> _readRoster(String scope) async {
+    final s = _parseScope(scope);
+    final rows =
+        await bridge.queryById('reltuple-${s.object}-${s.relation}');
+    final subjects = rows.isEmpty
+        ? const <String, dynamic>{}
+        : ((rows.first['data'] as Map?)?['subjects'] as Map?) ??
+            const <String, dynamic>{};
+    final out = <String>[];
+    subjects.forEach((subj, leafRaw) {
+      Map? leaf;
+      try {
+        leaf = leafRaw is String
+            ? jsonDecode(leafRaw) as Map
+            : (leafRaw as Map);
+      } catch (_) {
+        leaf = null;
+      }
+      final status = leaf?['status'];
+      if (status != null && status != 'active') return;
+      final p = subj.toString();
+      out.add(p.startsWith('user:') ? p.substring(5) : p);
+    });
+    out.sort();
+    return out;
+  }
+
+  Future<int> _currentEpoch(String scope) async {
+    final rows = await bridge.queryById('keyscope-$scope');
+    if (rows.isEmpty) return -1;
+    final e = (rows.first['data'] as Map?)?['currentEpoch'];
+    return e is num ? e.toInt() : -1;
+  }
+
+  Future<String> _freshScopeKey() async {
+    final kp = await bridge.cryptoKeygen();
+    final secret = base64Decode((kp['secret'] ?? '').toString());
+    return base64Encode(secret.sublist(0, 32)); // the 32-byte epoch secret; NEVER lands on chain
+  }
+
+  Future<String?> _memberPubKey(String principal,
+      {String? newcomer, String? newcomerPub, Map<String, String>? memberKeys}) async {
+    if (memberKeys != null && memberKeys[principal] != null) {
+      return memberKeys[principal];
+    }
+    if (newcomer == principal && newcomerPub != null) return newcomerPub;
+    // Published enc key (encKeyByPrincipal) — present only when the domain composed the registry; tolerate absence.
+    try {
+      final reg =
+          await bridge.query('encKeyByPrincipal', {'principal': principal});
+      if (reg.isNotEmpty) {
+        final pub = (reg.first['data'] as Map?)?['encPublicKey'];
+        if (pub != null && pub.toString().isNotEmpty) return pub.toString();
+      }
+    } catch (_) {/* not routed — fall through to the prior-wrap lane */}
+    // The member's most-recent WrappedKey pins the pubkey it was last sealed to (rotation needs no re-publish).
+    try {
+      final wraps = await bridge
+          .query('wrappedKeysByRecipient', {'recipientPrincipal': principal});
+      int bestEpoch = -1;
+      String? bestPub;
+      for (final w in wraps) {
+        final d = (w['data'] as Map?) ?? const {};
+        final pub = d['recipientPubKey'];
+        final ep = (d['epoch'] as num?)?.toInt() ?? 0;
+        if (pub != null && ep >= bestEpoch) {
+          bestEpoch = ep;
+          bestPub = pub.toString();
+        }
+      }
+      if (bestPub != null) return bestPub;
+    } catch (_) {/* not routed */}
+    return null;
+  }
+
+  Future<NomosEpochResult> _advance(
+    String scope, {
+    String? addPrincipal,
+    String? addPublicKey,
+    List<String> remove = const [],
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final roster = (await _readRoster(scope)).toSet();
+    if (addPrincipal != null) roster.add(addPrincipal);
+    roster.removeAll(remove);
+    final members = roster.toList()..sort();
+    // PRE-FIRE the fan-out gate: if the caller declared the roster it means to wrap, refuse on drift.
+    if (expectRoster != null) {
+      final want = expectRoster.toSet();
+      final missing = (want.difference(roster).toList())..sort();
+      final extra = members.where((m) => !want.contains(m)).toList();
+      if (missing.isNotEmpty || extra.isNotEmpty) {
+        throw EncryptionRosterMismatch(scope, missing, extra);
+      }
+    }
+    final key = scopeKey ?? await _freshScopeKey();
+    final wraps = <Map<String, Object?>>[];
+    for (final principal in members) {
+      final pub = await _memberPubKey(principal,
+          newcomer: addPrincipal, newcomerPub: addPublicKey, memberKeys: memberKeys);
+      if (pub == null) throw EncryptionMemberKeyMissing(principal, scope);
+      final w = await bridge.cryptoWrapKey(recipientPub: pub, scopeKey: key);
+      wraps.add({
+        'recipientPrincipal': principal,
+        'recipientPubKey': pub,
+        'hpkeEpk': (w['hpkeEpk'] ?? '').toString(),
+        'ct': (w['ct'] ?? '').toString(),
+      });
+    }
+    final epoch = (await _currentEpoch(scope)) + 1; // forward-only: strictly increments
+    final head = await bridge.offerDirective(
+      domain: domain,
+      directiveId: 'advanceKeyEpoch',
+      payload: {
+        'scope': scope,
+        'epoch': epoch,
+        'openedAt': openedAt ?? DateTime.now().toUtc().toIso8601String(),
+        'wraps': wraps,
+      },
+      actor: actor,
+      domainHash: domainHash,
+    );
+    return NomosEpochResult(head: head, epoch: epoch, roster: members);
+  }
+
+  /// Grant a newcomer + open a fresh epoch wrapping the key to EVERY member (incl. the newcomer). Dispatches
+  /// `grantDirective(grantPayload)` first, then `advanceKeyEpoch`. `publicKey` is the newcomer's X25519 key
+  /// (else resolved from an on-chain publishEncKey). Existing members' keys come from their prior wraps.
+  Future<NomosEpochResult> grantAndWrap({
+    required String principal,
+    String? publicKey,
+    String? scope,
+    required String grantDirective,
+    required Map<String, Object?> grantPayload,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final s = _defScope(scope);
+    await bridge.offerDirective(
+        domain: domain,
+        directiveId: grantDirective,
+        payload: grantPayload,
+        actor: actor,
+        domainHash: domainHash);
+    return _advance(s,
+        addPrincipal: principal,
+        addPublicKey: publicKey,
+        scopeKey: scopeKey,
+        memberKeys: memberKeys,
+        expectRoster: expectRoster,
+        openedAt: openedAt);
+  }
+
+  /// Revoke a member + open a fresh epoch re-wrapping the key to the SURVIVORS only. FORWARD-ONLY: the removed
+  /// member gets no NEW reads, but old ciphertext it already holds a key for stays readable (not re-encrypted).
+  Future<NomosEpochResult> revokeAndRotate({
+    required String principal,
+    String? scope,
+    required String revokeDirective,
+    required Map<String, Object?> revokePayload,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) async {
+    final s = _defScope(scope);
+    await bridge.offerDirective(
+        domain: domain,
+        directiveId: revokeDirective,
+        payload: revokePayload,
+        actor: actor,
+        domainHash: domainHash);
+    return _advance(s,
+        remove: [principal],
+        scopeKey: scopeKey,
+        memberKeys: memberKeys,
+        expectRoster: expectRoster,
+        openedAt: openedAt);
+  }
+
+  /// Routine rotation — open a fresh epoch re-wrapping the key to the CURRENT roster (no membership change).
+  Future<NomosEpochResult> rotate({
+    String? scope,
+    String? scopeKey,
+    Map<String, String>? memberKeys,
+    List<String>? expectRoster,
+    String? openedAt,
+  }) =>
+      _advance(_defScope(scope),
+          scopeKey: scopeKey,
+          memberKeys: memberKeys,
+          expectRoster: expectRoster,
+          openedAt: openedAt);
+}
+
 /// The result of [NomosBridge.offerCreates]: the new local [head] plus every aggregate the plan minted.
 class NomosOfferOutcome {
   final String head;
@@ -771,14 +1143,78 @@ class NomosBridge {
           Map<String, Object?> args) async =>
       _asMap(await _call('attestationSign', {'args': args}));
 
-  /// A declared query's rows from the local projection.
+  /// A declared query's rows from the local projection. `keys` (E2E sealing) injects the reader's held
+  /// scope keys so encrypted fields AEAD-open in-wasm; absent ⇒ they stay opaque envelopes (today's
+  /// behavior). `principal` stamps the private-read gate (defaults to the connection's bound principal).
+  /// Both are OMITTED from the wire when absent, so a public un-keyed read is byte-identical to before.
   Future<List<Map<String, dynamic>>> query(String queryId,
-          [Map<String, Object?> params = const {}]) async =>
-      _asRows(await _call('query', {'queryId': queryId, 'params': params}));
+          [Map<String, Object?> params = const {},
+          List<NomosScopeKey>? keys,
+          String? principal]) async =>
+      _asRows(await _call('query', {
+        'queryId': queryId,
+        'params': params,
+        ...?_readAuthArgs(keys, principal),
+      }));
+
+  /// A single aggregate by id (the by-id read). `keys`/`principal`: see [query].
+  Future<List<Map<String, dynamic>>> queryById(String id,
+          [List<NomosScopeKey>? keys, String? principal]) async =>
+      _asRows(await _call('queryById', {
+        'id': id,
+        ...?_readAuthArgs(keys, principal),
+      }));
+
+  /// The read auth sidecar (private reads + E2E): `keys`/`principal` as top-level call args, or null when
+  /// neither is present (so the wire is byte-identical to before this existed).
+  Map<String, Object?>? _readAuthArgs(List<NomosScopeKey>? keys, String? principal) {
+    final out = <String, Object?>{};
+    if (principal != null && principal.isNotEmpty) out['principal'] = principal;
+    if (keys != null && keys.isNotEmpty) out['keys'] = keys.map((k) => k.toJson()).toList();
+    return out.isEmpty ? null : out;
+  }
 
-  /// A single aggregate by id (the by-id read).
-  Future<List<Map<String, dynamic>>> queryById(String id) async =>
-      _asRows(await _call('queryById', {'id': id}));
+  /// E2E CRYPTO OPS (operator-blind sealing) — routed to the kernel via the WebView runner. XChaCha isn't in
+  /// WebCrypto/Dart, so these drive the wasm; the scope key + device secret are INJECTED per call and never
+  /// touch the chain. Mirror of the TS holon's crypto seam (@githolon/client).
+  /// Mint an X25519 device keypair for the handshake: `{secret, public}` (base64). Secret stays on device.
+  Future<Map<String, Object?>> cryptoKeygen() async =>
+      _asMap(await _call('cryptoKeygen'));
+
+  /// AUTHOR-SIDE SEAL: encrypt `plaintext` into its on-chain ciphertext envelope, bound to the scope + #58
+  /// stable sids (rename-safe). Returns the envelope string the encrypted field value is written as.
+  Future<String> cryptoSealField(
+          {required String scopeKey,
+          required String scope,
+          required int epoch,
+          required String aggSid,
+          required String fieldSid,
+          required String plaintext}) async =>
+      (_asMap(await _call('cryptoSealField', {
+        'scopeKey': scopeKey,
+        'scope': scope,
+        'epoch': epoch,
+        'aggSid': aggSid,
+        'fieldSid': fieldSid,
+        'plaintext': plaintext,
+      }))['envelope'] ?? '')
+          .toString();
+
+  /// Wrap a scope key TO a recipient's public key (committer side): `{hpkeEpk, ct}` base64 ciphertext.
+  Future<Map<String, Object?>> cryptoWrapKey(
+          {required String recipientPub, required String scopeKey}) async =>
+      _asMap(await _call('cryptoWrapKey',
+          {'recipientPub': recipientPub, 'scopeKey': scopeKey}));
+
+  /// Unwrap an on-chain WrappedKey with this device's secret → the base64 scope key (reader side).
+  Future<String> cryptoUnwrapKey(
+          {required String secret,
+          required String hpkeEpk,
+          required String ct}) async =>
+      (_asMap(await _call('cryptoUnwrapKey',
+                  {'secret': secret, 'hpkeEpk': hpkeEpk, 'ct': ct}))['scopeKey'] ??
+              '')
+          .toString();
 
   /// THE SPATIAL READ: rows of the declared spatial index's of-type whose geometry
   /// intersects [bbox] — an R*Tree probe on the local projection, same row shape as [query].

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/dsl",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "type": "module",
   "description": "Nomos 2 domain-authoring DSL: aggregates + directives in TS, executed and encoded to the Rust kernel's wire shapes.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -46,7 +46,8 @@
     "dart",
     "!dart/.dart_tool",
     "!dart/build",
-    "compile_package.mjs"
+    "compile_package.mjs",
+    "check_package.mjs"
   ],
   "publishConfig": {
     "access": "public"