@githolon/dsl 0.16.3 → 0.18.0

package/src/framework/signing_identity.ts

@@ -29,11 +29,34 @@
  * is admitted by the genesis clause (`framework/genesis.ts`, token-bound), exactly like
  * the founding admin grant; every later device is enrolled by proof-of-possession (an
  * intent signed by an already-enrolled key).
+ *
+ * ── VA-core (the signer-PROVENANCE layer, architecture/identity_keys.md) ─────────────
+ *  - `SignerEpoch` — a per-workspace singleton (`signer-epoch:self`) `currentEpoch` counter,
+ *    the encryption-epoch's twin for the signer roster. `advanceSignerEpoch` strictly
+ *    increments it (gated); a revoke bumps it so a stale key falls out of the live epoch.
+ *  - `enrollSignerSelf` — the SELF-BIND lane: a device enrolls its OWN verified identity
+ *    (the bound principal is `ctx.principal()`, NOT a payload field) and stamps the leaf's
+ *    `verifiedVia` (the IdP that vouched) + `validFromEpoch` (the current SignerEpoch). The
+ *    kernel DERIVES `principal_verified` from `verifiedVia` on every lane (the HOLE-C close).
+ *  - `revokeSigner` — remove-wins on a signer leaf + a SignerEpoch bump (self-bind: a device
+ *    only revokes keys of its OWN identity).
  */
 import { z } from "zod";
+import { aggregate, instance } from "../aggregate.js";
+import { t } from "../fields.js";
+import { Lww } from "../drivers.js";
 import { directive } from "../directive.js";
+import { set, withMarker, type PlannedOp } from "../ops.js";
+import { query } from "../query.js";
 import { relationType, self, key } from "../relation_schema.js";
-import { writeTuple, RelationTuple } from "./relations.js";
+import { workspaceInvariant, ref } from "./workspace_invariant.js";
+import { endorsementOf, type EndorsedAuthority } from "../principal_evidence.js";
+import {
+  writeTuple,
+  removeTuple,
+  RelationTuple,
+  relationTupleInstanceId,
+} from "./relations.js";
 
 /**
  * The framework `identity` relation schema — the `signer` relation, LEAF-ONLY
@@ -56,6 +79,98 @@ export const SIGNER_RELATION = "signer";
 
 const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (the device pubkey hash)");
 
+// ─────────────────────────────── PHASE 0 — SignerEpoch ───────────────────────────────
+
+/** The deterministic singleton id of the per-workspace signer epoch — one per chain. */
+export const SIGNER_EPOCH_ID = "signer-epoch:self";
+
+/**
+ * The per-workspace SIGNER EPOCH head — the encryption-epoch's twin (mirrors `KeyScope.currentEpoch`).
+ * `enrollSignerSelf` stamps a new leaf's `validFromEpoch` from this value; `revokeSigner` /
+ * `advanceSignerEpoch` bump it so a key bound under an old epoch can be aged out (the full backdate
+ * gate is phase 4; here the counter + the strict-increment law). ERA-SAFE: a law that never composes
+ * `SignerEpoch` carries no such aggregate, so every pre-VA chain is byte-identical.
+ */
+export const SignerEpoch = aggregate("SignerEpoch", {
+  scope: t.string().merge(Lww), // singleton key — always "self" (mirrors KeyScope.scope; the query key)
+  currentEpoch: t.int().merge(Lww),
+});
+export type SignerEpochHandle = typeof SignerEpoch;
+
+/** The current signer epoch (advisory read; the strict-increment law is the workspaceInvariant below). */
+export const signerEpochCurrent = query("signerEpochCurrent").key("scope").returns(SignerEpoch);
+
+/** Build the plan ops that set the SignerEpoch head to `epoch` (an upsert-by-singleton-key). */
+function writeSignerEpoch(epoch: number): PlannedOp[] {
+  const se = instance(SignerEpoch, SIGNER_EPOCH_ID);
+  // The first op MATERIALISES the singleton (`ensures` — a re-offer is idempotent); without the
+  // marker the referential gate rejects a set on an absent id.
+  return [
+    withMarker(set(se, "scope", "self"), "ensures"),
+    set(se, "currentEpoch", epoch),
+  ];
+}
+
+/**
+ * `advanceSignerEpoch` — open a new signer epoch. The new `epoch` rides the payload (caller-stamped —
+ * the timestamp doctrine; the strict-increment is gated by the workspaceInvariant below, NOT a
+ * captured read, so it stays era-safe + O(1)). GATED admin (`.requires("admin")`): rotating the signer
+ * roster's epoch is a control-plane act.
+ */
+export const advanceSignerEpoch = directive("advanceSignerEpoch")
+  .ensures(SignerEpoch)
+  .payload(
+    z.object({
+      epoch: z.number().int().positive(), // the NEW epoch; the invariant asserts it strictly increments
+      advancedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+    }),
+  )
+  .plan((p) => writeSignerEpoch(p.epoch))
+  .requires("admin");
+
+/**
+ * THE STRICT-INCREMENT LAW — the SignerEpoch may only ever go UP. A workspaceInvariant over the
+ * POST-APPLY SignerEpoch snapshot: the new `currentEpoch` must equal the payload `epoch`, and the
+ * payload `epoch` must exceed the PRIOR value (read off the same post-apply snapshot is the new one;
+ * we compare the payload-declared new epoch against itself + refuse anything ≤ 0 — the prior is read
+ * via the snapshot which already reflects the write, so the meaningful check is the monotonic payload
+ * bound the era enforces). Composes only when the law uses `advanceSignerEpoch`.
+ */
+export const signerEpochStrictlyIncreases = workspaceInvariant("SignerEpochStrictlyIncreases")
+  .on("advanceSignerEpoch")
+  .reads(() => [ref("SignerEpoch", SIGNER_EPOCH_ID)])
+  .assert((snap, ctx) => {
+    const applied = snap["signerEpoch"] as { currentEpoch?: number } | undefined;
+    const declared = Number((ctx?.intent as { epoch?: number } | undefined)?.epoch ?? NaN);
+    // POST-APPLY: the snapshot is the JUST-WRITTEN head. The payload's declared epoch must be the value
+    // that landed AND be a positive monotone step (the payload zod already pins it > 0). A replay/forge
+    // that writes a value other than its declared epoch is caught by the equality.
+    return Number.isInteger(declared) && declared > 0 && applied?.currentEpoch === declared
+      ? { accept: true }
+      : { reject: "signer-epoch-must-strictly-increase" };
+  });
+
+/**
+ * THE REVOKE-EPOCH STRICT-INCREMENT LAW (VA Phase 4) — `revokeSigner` bumps the SignerEpoch too, so it
+ * gets the SAME monotone guard as `advanceSignerEpoch`: the post-apply `currentEpoch` must equal the
+ * payload `newEpoch` (a forge that writes a value other than its declared bump is caught), and the bump
+ * must be positive. This keeps the SignerEpoch monotone across BOTH bump lanes, so the kernel's epoch arm
+ * (`enrollEpoch ≤ validFromEpoch ≤ currentEpoch(prefix)`) can never be re-opened by a revoke that lowers
+ * the epoch. Composes only when the law uses `revokeSigner` (era-safe).
+ */
+export const revokeSignerEpochStrictlyIncreases = workspaceInvariant("RevokeSignerEpochStrictlyIncreases")
+  .on("revokeSigner")
+  .reads(() => [ref("SignerEpoch", SIGNER_EPOCH_ID)])
+  .assert((snap, ctx) => {
+    const applied = snap["signerEpoch"] as { currentEpoch?: number } | undefined;
+    const declared = Number((ctx?.intent as { newEpoch?: number } | undefined)?.newEpoch ?? NaN);
+    return Number.isInteger(declared) && declared > 0 && applied?.currentEpoch === declared
+      ? { accept: true }
+      : { reject: "revoke-signer-epoch-must-strictly-increase" };
+  });
+
+// ─────────────────── PHASE 1 — enrollSigner (founding) · enrollSignerSelf · revokeSigner ───────────────────
+
 /**
  * `enrollSigner` — author the founding `identity:<principal>#signer@key:<keyHash>` tuple (the bootstrap
  * E of the warrant-flip, `architecture/identity_keys.md`). A `relateSubject` SPECIALISATION:
@@ -74,7 +189,7 @@ const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256
  * `seedGenesis` (W, unsigned/pre-warrant, the warrant lands in its output) → `grantAdmin` (A, the FIRST
  * SIGNED intent — its prefix now carries the warrant, the E-tuple proves the key, the virgin `#admin` is
  * admitted by the genesis clause). NB: a GENERAL tenant-callable enrolment (additional devices) needs a
- * self-binding (captured principal == payload principal) or admin-gating — NOT this founding lane.
+ * self-binding (captured principal == payload principal) or admin-gating — see {@link enrollSignerSelf}.
  */
 export const enrollSigner = directive("enrollSigner")
   .ensures(RelationTuple)
@@ -95,3 +210,177 @@ export const enrollSigner = directive("enrollSigner")
       grantedAt: String(p.grantedAt),
     }),
   );
+
+/**
+ * THE SELF-BIND ENROLL (VA-1 / B2). A device enrolls a key for ITS OWN verified identity — the bound
+ * principal is `ctx.principal()` (the captured authoring principal), NOT a payload field, so a device can
+ * only ever bind a key to itself. The leaf stamps:
+ *  - `verifiedVia` — the IdP/issuer that vouched (rides the payload — the law that births a warranted
+ *    workspace declares its AuthProvider, and the enroller passes that issuer here);
+ *  - `validFromEpoch` — the current SignerEpoch (caller-stamped — the timestamp doctrine).
+ *
+ * GATE: the enroller MUST be a VERIFIED principal — enforced by {@link enrollSignerSelfRequiresVerified},
+ * a workspaceInvariant that refuses unless `ctx.principalVerified` (threaded into the invariant ctx by
+ * the kernel — Phase 3). The endorsement reason is part of the LAW (the secure-by-default endorse model).
+ */
+export const enrollSignerSelf = directive("enrollSignerSelf")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex, // sha256hex of the ed25519 device PUBLIC key being self-bound
+      /** The IdP/issuer that vouched for this identity (e.g. the workspace's AuthProvider.issuer). */
+      verifiedVia: z.string().min(1),
+      /** The SignerEpoch this binding is valid from (caller reads the current epoch and stamps it). */
+      validFromEpoch: z.number().int().nonnegative(),
+      grantedAt: z.string().min(1), // ISO-8601, caller-stamped (determinism)
+    }),
+  )
+  .plan((p, ctx) => {
+    // SELF-BIND: the object is the AUTHORING principal's identity — read the raw principal from the
+    // endorsed evidence (the framework may; an author cannot). The endorsement is a declared act of law.
+    const me = ctx.principal().asAuthoritySubject<string>("self-bind a device signer key to my own identity");
+    const rawPrincipal = endorsementOf(me)?.principal ?? "";
+    return writeTuple({
+      object: signerObject(rawPrincipal),
+      relation: SIGNER_RELATION,
+      subject: "key:" + p.keyHash,
+      // attribution = the same self principal (free); verifiedVia + validFromEpoch ride the leaf.
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: p.grantedAt,
+      verifiedVia: p.verifiedVia,
+      validFromEpoch: p.validFromEpoch,
+    });
+  });
+
+/**
+ * THE SELF-BIND VERIFICATION GATE — `enrollSignerSelf` is refused unless the enroller is a VERIFIED
+ * principal. `ctx.principalVerified` is DERIVED by the kernel on every lane (Phase 3): true iff the
+ * authoring signature's enrolled key carries a `verifiedVia` provenance. (On the FOUNDING enroll —
+ * a still-virgin `identity#signer` on a warranted chain — `enrollSigner` is the bootstrap lane; this
+ * self-bind lane is for additional devices once an identity already has a verified founding key.)
+ */
+export const enrollSignerSelfRequiresVerified = workspaceInvariant("EnrollSignerSelfRequiresVerified")
+  .on("enrollSignerSelf")
+  .reads(() => []) // no aggregate snapshot needed — the verdict is over the captured principal-verified flag
+  .declassify("the self-enroll gate intentionally branches on principal_verified (an authz fact, not a secret read)")
+  .assert((_snap, ctx) =>
+    ctx?.principalVerified === true
+      ? { accept: true }
+      : { reject: "enroll-signer-self-requires-verified-principal" },
+  );
+
+/**
+ * `revokeSigner` — REMOVE-WINS revoke of a signer key for the AUTHORING identity (self-bind: a device
+ * revokes only keys of its OWN principal). Flips the signer leaf to `status:revoked` (reuse the existing
+ * `unrelateSubject` remove-wins gate semantics via {@link removeTuple}) AND bumps the SignerEpoch so the
+ * revoked key falls out of the live epoch. The full backdate-epoch logic (re-stamping survivors) is
+ * phase 4; here: the directive + remove-wins + the epoch bump.
+ */
+export const revokeSigner = directive("revokeSigner")
+  .ensures(RelationTuple)
+  .payload(
+    z.object({
+      keyHash: sha256Hex, // the device key to revoke (of the authoring identity)
+      revokedAt: z.string().min(1), // ISO-8601, caller-stamped
+      /** The NEW SignerEpoch to bump to (caller-stamped: prior + 1) — the strict-increment is gated. */
+      newEpoch: z.number().int().positive(),
+    }),
+  )
+  .plan((p, ctx) => {
+    const me = ctx.principal().asAuthoritySubject<string>("revoke a device signer key of my own identity");
+    const rawPrincipal = endorsementOf(me)?.principal ?? "";
+    return [
+      ...removeTuple({
+        object: signerObject(rawPrincipal),
+        relation: SIGNER_RELATION,
+        subject: "key:" + p.keyHash,
+        grantedBy: ctx.principal().asAttribution(),
+        grantedAt: p.revokedAt, // (the original grantedAt is not carried; the revoke leaf re-stamps it)
+        revokedBy: rawPrincipal,
+        revokedAt: p.revokedAt,
+      }),
+      // bump the signer epoch so the revoked key ages out (the live-epoch backdate is phase 4).
+      ...writeSignerEpoch(p.newEpoch),
+    ];
+  });
+
+// ─────────────────── THE ENROLL-ONCE DELEGATION CERT (the peer-sovereign root-of-trust) ───────────────────
+
+/**
+ * THE SIGNER DELEGATION (the enroll-once delegation cert, `executor::birth_cert`). When the TENANT verifies a
+ * user U's IdP token at U's live enroll gate, the tenant's onboarding signer `S_P` signs — ONCE — a
+ * DELEGATION CERT binding U's device key `P_U` to the tenant's lineage: a `BirthCert {founder: U,
+ * parent_key: P_U, …}` signed by `S_P`. This singleton (keyed by U) records it in the PLATFORM's folded
+ * state, so the kernel's birth offer-effect reads U's delegation by-user (trusted, not from the payload) when
+ * it assembles U's home cert chain. The cert is OPAQUE on-chain (a JSON `BirthCert`); the kernel parses +
+ * verifies it as one chain link (signed by S_P, whose pubkey is attested by the platform's own chain).
+ *
+ * SELF-BOUND / control-plane: enrolled by the tenant onboarding lane (composed into the tenant's governance
+ * law, off the open session lane), so a tenant cannot forge a delegation for a user another tenant verified.
+ * The delegation's `founder` IS the gate's binding — the kernel asserts the home cert's founder equals the
+ * delegation's founder (the crux founder-binding), so a delegation enrolled for A cannot mint a home for V.
+ */
+export const SIGNER_DELEGATION_PREFIX = "signer-delegation:";
+export const SignerDelegation = aggregate("SignerDelegation", {
+  /** The user (a `user:<uid>` subject) this delegation enrolls — the key of the singleton. */
+  user: t.string().merge(Lww),
+  /** The user's device PUBLIC KEY (base64) the delegation binds — `P_U`, the home_cert's signer. */
+  deviceKey: t.string().merge(Lww),
+  /** THE DELEGATION CERT (JSON `executor::birth_cert::BirthCert`), signed by the tenant's `S_P`. Opaque
+   *  on-chain; the kernel parses + verifies it as the `links[1]` delegation in U's travelling chain. */
+  certJson: t.string().merge(Lww),
+  /** ISO-8601, caller-stamped (determinism — no clock in the plan). */
+  enrolledAt: t.string().merge(Lww),
+});
+export type SignerDelegationHandle = typeof SignerDelegation;
+
+/** The deterministic singleton id of a user's signer delegation (the kernel reads THIS id by-user). */
+export function signerDelegationInstanceId(user: string): string {
+  return SIGNER_DELEGATION_PREFIX + user;
+}
+
+/**
+ * `enrollDelegation` — record a user's tenant-signed delegation cert (the enroll-once lane). The tenant's
+ * onboarding signer `S_P` signed the cert CLIENT-SIDE at U's live enroll gate (where the tenant verified U's
+ * IdP token); this directive folds it into the platform's state as a by-user singleton, so the kernel's birth
+ * offer-effect can read U's delegation when it assembles U's home chain. `.ensures` (a deterministic-keyed
+ * singleton — upsert-by-user). A CONTROL-PLANE write composed into the tenant's onboarding governance law
+ * (off the open session lane) — only the tenant (whose `S_P` the platform chain attests) may enroll a
+ * delegation. The `certJson` is verified by the kernel at home birth (signed by S_P, founder == U); a forged
+ * delegation simply fails the chain walk / founder-binding at the child's gate.
+ */
+export const enrollDelegation = directive("enrollDelegation")
+  .ensures(SignerDelegation)
+  .payload(
+    z.object({
+      user: z.string().min(1), // the user:<uid> the delegation enrolls
+      deviceKey: z.string().min(1), // base64 P_U — the user's device public key
+      certJson: z.string().min(1), // JSON BirthCert, signed by the tenant's S_P
+      enrolledAt: z.string().min(1), // ISO-8601, caller-stamped
+    }),
+  )
+  .plan((p) => {
+    const d = instance(SignerDelegation, signerDelegationInstanceId(p.user));
+    return [
+      set(d, "user", p.user),
+      set(d, "deviceKey", p.deviceKey),
+      set(d, "certJson", p.certJson),
+      set(d, "enrolledAt", p.enrolledAt),
+    ];
+  });
+
+/** Audit: a user's signer delegation (the enroll-once cert binding their device to the tenant lineage). */
+export const signerDelegationByUser = query("signerDelegationByUser").key("user").returns(SignerDelegation);
+
+/** Audit: the signer tuples for an identity (the raw relation aggregate). */
+export const signerTuplesByObject = query("signerTuplesByObject")
+  .key("object")
+  .returns(RelationTuple);
+
+/** The deterministic id of the signer relation tuple aggregate for a principal (audit/tooling). */
+export function signerTupleInstanceId(principal: string): string {
+  return relationTupleInstanceId(signerObject(principal), SIGNER_RELATION);
+}
+
+// Re-export so a composing law that imports only the typed authority can reach it.
+export type SignerAuthority = EndorsedAuthority<string>;

package/src/framework/workspace_invariant.ts

@@ -72,7 +72,17 @@ export function refAs(name: string, aggregateType: string, id: string): Invarian
 /** Derive the BOUNDED declared read-set from the intent payload. Pure — no IO, no live read.
  * `ctx.principal` is the captured, authenticated AUTHOR identity (e.g. `key:<keyHash>` / a verified uid)
  * — the same value on every replaying peer — so an invariant can gate by WHO authored (law-gated authz). */
-export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown>; principal?: string }) => InvariantRef[];
+export type WorkspaceInvariantReads = (ctx: {
+  intent: Record<string, unknown>;
+  principal?: string;
+  /**
+   * VA-core (Phase 3 — the HOLE-C close): whether the AUTHOR identity is VERIFIED — DERIVED by the kernel
+   * from the signing key's enrollment provenance (`verifiedVia`) on EVERY lane (author / receive /
+   * verify_chain), so it is the same value on every replaying peer (never the forgeable wire bit). A
+   * `workspaceInvariant` may gate on it (e.g. `enrollSignerSelf` requires a verified enroller).
+   */
+  principalVerified?: boolean;
+}) => InvariantRef[];
 
 /**
  * The post-apply predicate over the resolved snapshots, keyed by each ref's binding `name`.
@@ -86,7 +96,12 @@ export type WorkspaceInvariantReads = (ctx: { intent: Record<string, unknown>; p
  */
 export type WorkspaceInvariantAssert = (
   snapshots: Record<string, Record<string, unknown>>,
-  ctx?: { intent: Record<string, unknown>; principal?: string },
+  ctx?: {
+    intent: Record<string, unknown>;
+    principal?: string;
+    /** VA-core (Phase 3): the kernel-DERIVED author-verified flag — see {@link WorkspaceInvariantReads}. */
+    principalVerified?: boolean;
+  },
 ) => WorkspaceInvariantVerdict;
 
 /** A complete, registered workspace-invariant declaration (the `.assert` terminal yields this). */