@githolon/dsl 0.50.0 → 0.51.0

package/src/codegen_ts.ts

@@ -582,6 +582,10 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
           `  cryptoSealField?(args: { scopeKey: string; scope: string; epoch: number; aggSid: string; fieldSid: string; plaintext: string }): Promise<string>;`,
           `  /** Unwrap an on-chain WrappedKey with this device's secret → the base64 scope key (default KeyStore). */`,
           `  cryptoUnwrapKey?(args: { secret: string; hpkeEpk: string; ct: string }): Promise<string>;`,
+          `  /** OWNER CEREMONY (slice 2): HPKE-wrap a scope epoch secret TO a member's published X25519 pubkey. */`,
+          `  cryptoWrapKey?(args: { recipientPub: string; scopeKey: string }): Promise<{ hpkeEpk: string; ct: string }>;`,
+          `  /** OWNER CEREMONY (slice 2): mint a fresh X25519 keypair — the source of a fresh epoch secret (32 bytes of its secret). */`,
+          `  cryptoKeygen?(): Promise<{ public: string; secret: string }>;`,
         ]
       : [
           `  query(queryId: string, params?: Record<string, unknown>): Promise<unknown>;`,
@@ -721,6 +725,165 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       `  };`,
       `}`,
       ``,
+      `// ── E2E OWNER CEREMONY (the sealing client, slice 2) — grantAndWrap / revokeAndRotate / rotate ──`,
+      `// The owner-side twin of the KeyStore. It composes the framework key-epoch fan-out (\`advanceKeyEpoch\`,`,
+      `// dispatched by its REAL id — never an \`export const alias\`) 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.`,
+      ``,
+      `/** Base64 ⇄ bytes that work in both the browser (atob/btoa) and Node (Buffer) — the generated`,
+      ` *  client is zero-import, so it derives a fresh 32-byte epoch secret from a keygen without a lib. */`,
+      `const _b64ToBytes = (b64: string): Uint8Array => {`,
+      `  if (typeof atob === "function") { const s = atob(b64); const u = new Uint8Array(s.length); for (let i = 0; i < s.length; i++) u[i] = s.charCodeAt(i); return u; }`,
+      `  return Uint8Array.from((globalThis as unknown as { Buffer: { from(s: string, e: string): Uint8Array } }).Buffer.from(b64, "base64"));`,
+      `};`,
+      `const _bytesToB64 = (u: Uint8Array): string => {`,
+      `  if (typeof btoa === "function") { let s = ""; for (const b of u) s += String.fromCharCode(b); return btoa(s); }`,
+      `  return (globalThis as unknown as { Buffer: { from(u: Uint8Array): { toString(e: string): string } } }).Buffer.from(u).toString("base64");`,
+      `};`,
+      ``,
+      `/** 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 member`,
+      ` *  with no key is "not yet a member", per e2e_encryption.md's FOOTGUNS). */`,
+      `export class EncryptionMemberKeyMissing extends Error {`,
+      `  readonly code = "nomos.crypto.member_key_missing";`,
+      `  readonly recommendedAction = "publishEncKey";`,
+      `  constructor(readonly principal: string, readonly scope: string) {`,
+      "    super(`cannot wrap the \"${scope}\" scope key to member \"${principal}\": no encryption public key on chain (publishEncKey) and none supplied — a keyless member is not yet wrappable (fail-closed)`);",
+      `    this.name = "EncryptionMemberKeyMissing";`,
+      `  }`,
+      `}`,
+      ``,
+      `/** 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 on the chain. */`,
+      `export class EncryptionRosterMismatch extends Error {`,
+      `  readonly code = "nomos.crypto.roster_mismatch";`,
+      `  readonly recommendedAction = "reconcileRoster";`,
+      `  constructor(readonly scope: string, readonly missing: readonly string[], readonly extra: readonly string[]) {`,
+      "    super(`roster for \"${scope}\" != expected (the fan-out gate would refuse): missing [${missing.join(\", \")}], unexpected [${extra.join(\", \")}]`);",
+      `    this.name = "EncryptionRosterMismatch";`,
+      `  }`,
+      `}`,
+      ``,
+      `/** The owner-ceremony surface — attached as \`<domain>Client(holon, { actor }).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. */`,
+      `export interface NomosEncryption {`,
+      `  /** The encryption scopes this domain defines (each a \`requires(cap)\`). */`,
+      `  readonly scopes: readonly string[];`,
+      `  /** The CURRENT roster of a scope (active direct-grant members, principal-form). Defaults to the sole scope. */`,
+      `  roster(scope?: string): Promise<string[]>;`,
+      `  /** 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. */`,
+      `  grantAndWrap(args: { principal: string; publicKey?: string; scope?: string; grantDirective: string; grantPayload: Record<string, unknown>; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `  /** 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). */`,
+      `  revokeAndRotate(args: { principal: string; scope?: string; revokeDirective: string; revokePayload: Record<string, unknown>; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `  /** Routine rotation — open a fresh epoch re-wrapping the key to the CURRENT roster (no membership change). */`,
+      `  rotate(args?: { scope?: string; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }>;`,
+      `}`,
+      ``,
+      `/** Build the owner ceremony for one domain (thin: all mechanism lives here; the factory just wires it). */`,
+      `function _ownerEncryption(holon: NomosHolon, cfg: { domain: string; domainHash?: string; actor?: string; scopes: readonly string[] }): NomosEncryption {`,
+      `  const { domain, domainHash, actor, scopes } = cfg;`,
+      `  const defScope = (scope?: string): string => {`,
+      `    if (scope) return scope;`,
+      `    if (scopes.length === 1) return scopes[0]!;`,
+      "    throw new Error(`this domain defines ${scopes.length} encryption scopes [${scopes.join(\", \")}] — pass { scope } to pick one`);",
+      `  };`,
+      `  // A BARE scope IS \`workspace:self#<relation>\` (the era rule); a per-record scope is \`<type>:<id>#<relation>\`.`,
+      `  const parseScope = (scope: string): { object: string; relation: string } => {`,
+      `    const h = scope.indexOf("#");`,
+      `    return h < 0 ? { object: "workspace:self", relation: scope } : { object: scope.slice(0, h), relation: scope.slice(h + 1) };`,
+      `  };`,
+      `  const readRoster = async (scope: string): Promise<string[]> => {`,
+      `    const { object, relation } = parseScope(scope);`,
+      "    const rows = (await holon.queryById(`reltuple-${object}-${relation}`)) as { data?: { subjects?: Record<string, unknown> } }[] | undefined;",
+      `    const subjects = rows?.[0]?.data?.subjects ?? {};`,
+      `    const out: string[] = [];`,
+      `    for (const [subj, leafRaw] of Object.entries(subjects)) {`,
+      `      let leaf: { status?: string };`,
+      `      try { leaf = typeof leafRaw === "string" ? JSON.parse(leafRaw) : (leafRaw as { status?: string }); } catch { leaf = {}; }`,
+      `      if (leaf?.status !== undefined && leaf.status !== "active") continue;`,
+      `      out.push(subj.startsWith("user:") ? subj.slice(5) : subj);`,
+      `    }`,
+      `    return out.sort();`,
+      `  };`,
+      `  const currentEpoch = async (scope: string): Promise<number> => {`,
+      "    const rows = (await holon.queryById(`keyscope-${scope}`)) as { data?: { currentEpoch?: number } }[] | undefined;",
+      `    const e = rows?.[0]?.data?.currentEpoch;`,
+      `    return typeof e === "number" ? e : -1;`,
+      `  };`,
+      `  const freshScopeKey = async (): Promise<string> => {`,
+      `    if (!holon.cryptoKeygen) throw new Error("this holon predates E2E keygen — upgrade @githolon/client");`,
+      `    const kp = await holon.cryptoKeygen();`,
+      `    return _bytesToB64(_b64ToBytes(kp.secret).subarray(0, 32)); // the 32-byte epoch secret; NEVER lands on chain`,
+      `  };`,
+      `  const memberPubKey = async (principal: string, hints: { publicKey?: string; principal?: string; memberKeys?: Record<string, string> }): Promise<string | undefined> => {`,
+      `    if (hints.memberKeys?.[principal]) return hints.memberKeys[principal];`,
+      `    if (hints.principal === principal && hints.publicKey) return hints.publicKey;`,
+      `    // Published enc key (encKeyByPrincipal) — present only when the domain composed the registry; tolerate absence.`,
+      `    try {`,
+      `      const reg = (await holon.query("encKeyByPrincipal", { principal })) as { data?: { encPublicKey?: string } }[] | undefined;`,
+      `      const pub = Array.isArray(reg) ? reg[0]?.data?.encPublicKey : undefined;`,
+      `      if (pub) return pub;`,
+      `    } 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 {`,
+      `      const wraps = (await holon.query("wrappedKeysByRecipient", { recipientPrincipal: principal })) as { data?: { epoch?: number; recipientPubKey?: string } }[] | undefined;`,
+      `      let best: { epoch: number; pub: string } | undefined;`,
+      `      for (const w of Array.isArray(wraps) ? wraps : []) { const d = w.data ?? {}; if (d.recipientPubKey && (best === undefined || (d.epoch ?? 0) >= best.epoch)) best = { epoch: d.epoch ?? 0, pub: d.recipientPubKey }; }`,
+      `      if (best) return best.pub;`,
+      `    } catch { /* not routed */ }`,
+      `    return undefined;`,
+      `  };`,
+      `  const advance = async (scope: string, opts: { add?: { principal: string; publicKey?: string }; remove?: readonly string[]; scopeKey?: string; memberKeys?: Record<string, string>; expectRoster?: readonly string[]; openedAt?: string }): Promise<{ head: string; epoch: number; roster: string[] }> => {`,
+      `    const roster = new Set(await readRoster(scope));`,
+      `    if (opts.add) roster.add(opts.add.principal);`,
+      `    for (const p of opts.remove ?? []) roster.delete(p);`,
+      `    const members = [...roster].sort();`,
+      `    // PRE-FIRE the fan-out gate: if the caller declared the roster it means to wrap, refuse on drift.`,
+      `    if (opts.expectRoster !== undefined) {`,
+      `      const want = new Set(opts.expectRoster);`,
+      `      const missing = [...want].filter((m) => !roster.has(m)).sort();`,
+      `      const extra = members.filter((m) => !want.has(m));`,
+      `      if (missing.length || extra.length) throw new EncryptionRosterMismatch(scope, missing, extra);`,
+      `    }`,
+      `    const key = opts.scopeKey ?? await freshScopeKey();`,
+      `    if (!holon.cryptoWrapKey) throw new Error("this holon predates E2E wrap — upgrade @githolon/client");`,
+      `    const wraps: { recipientPrincipal: string; recipientPubKey: string; hpkeEpk: string; ct: string }[] = [];`,
+      `    for (const principal of members) {`,
+      `      const pub = await memberPubKey(principal, { publicKey: opts.add?.publicKey, principal: opts.add?.principal, memberKeys: opts.memberKeys });`,
+      `      if (!pub) throw new EncryptionMemberKeyMissing(principal, scope);`,
+      `      const w = await holon.cryptoWrapKey({ recipientPub: pub, scopeKey: key });`,
+      `      wraps.push({ recipientPrincipal: principal, recipientPubKey: pub, hpkeEpk: w.hpkeEpk, ct: w.ct });`,
+      `    }`,
+      `    const epoch = (await currentEpoch(scope)) + 1; // forward-only: strictly increments`,
+      "    const head = await holon.offerDirective(domain, \"advanceKeyEpoch\", { scope, epoch, openedAt: opts.openedAt ?? new Date().toISOString(), wraps }, { domainHash, actor });",
+      `    return { head, epoch, roster: members };`,
+      `  };`,
+      `  return {`,
+      `    scopes,`,
+      `    roster: (scope) => readRoster(defScope(scope)),`,
+      `    async grantAndWrap(args) {`,
+      `      const scope = defScope(args.scope);`,
+      `      await holon.offerDirective(domain, args.grantDirective, args.grantPayload, { domainHash, actor });`,
+      `      return advance(scope, { add: { principal: args.principal, publicKey: args.publicKey }, scopeKey: args.scopeKey, memberKeys: args.memberKeys, expectRoster: args.expectRoster, openedAt: args.openedAt });`,
+      `    },`,
+      `    async revokeAndRotate(args) {`,
+      `      const scope = defScope(args.scope);`,
+      `      await holon.offerDirective(domain, args.revokeDirective, args.revokePayload, { domainHash, actor });`,
+      `      return advance(scope, { remove: [args.principal], scopeKey: args.scopeKey, memberKeys: args.memberKeys, expectRoster: args.expectRoster, openedAt: args.openedAt });`,
+      `    },`,
+      `    async rotate(args) {`,
+      `      const scope = defScope(args?.scope);`,
+      `      return advance(scope, { scopeKey: args?.scopeKey, memberKeys: args?.memberKeys, expectRoster: args?.expectRoster, openedAt: args?.openedAt });`,
+      `    },`,
+      `  };`,
+      `}`,
+      ``,
     );
   }
 
@@ -1011,6 +1174,16 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       const r = encMap?.[domain]?.reads?.[typeId];
       return r === undefined ? [] : [...new Set(Object.values(r).map((x) => x.scope))].sort();
     };
+    // The DISTINCT encryption scopes this domain defines (across encrypted reads + sealing directives) —
+    // the set the owner ceremony rotates. Empty ⇒ no `encryption` surface is emitted for this domain.
+    const domScopes: string[] = (() => {
+      const dm = encMap?.[domain];
+      if (dm === undefined) return [];
+      const s = new Set<string>();
+      for (const r of Object.values(dm.reads)) for (const f of Object.values(r)) s.add(f.scope);
+      for (const dir of Object.values(dm.directives)) for (const f of Object.values(dir)) s.add(f.scope);
+      return [...s].sort();
+    })();
     for (const d of dirs) {
       let payloadName = `${cap(d.id)}Payload`;
       if (usedPayloadNames.has(payloadName)) payloadName = `${cap(camel(domain))}${cap(d.id)}Payload`;
@@ -1204,6 +1377,14 @@ export function generateTsClient(modules: readonly DomainModule[], opts: TsClien
       ...(opts.interface !== undefined
         ? [`    interface: ${interfaceConstName(opts.packageName)}[${JSON.stringify(domain)}],`]
         : []),
+      // THE OWNER CEREMONY (slice 2): only for a domain that actually defines an encryption scope.
+      ...(domScopes.length > 0
+        ? [
+            `    /** OWNER CEREMONY (slice 2): grantAndWrap / revokeAndRotate / rotate — the operator-blind`,
+            `     *  key-epoch handshake as one call. Bind \`{ actor }\` (the owner) to author the fan-out. */`,
+            `    encryption: _ownerEncryption(holon, { domain: ${JSON.stringify(domain)}, domainHash, actor, scopes: ${JSON.stringify(domScopes)} }) as NomosEncryption,`,
+          ]
+        : []),
       ...methods,
       `  };`,
       `}`,