@githolon/dsl 0.108.6 → 0.110.0

package/src/framework/principal_enrollment.ts

@@ -0,0 +1,302 @@
+// 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.
+
+/**
+ * framework/principal_enrollment.ts — how the FIRST key of a principal reaches the ledger
+ * (identity target model D22: the kernel is the authentication).
+ *
+ * `admit`'s whole authentication rule is: the signature verifies under key K, K is an active signer of
+ * the claimed principal P in parent state (`identity:P#signer@key:<sha256(K)>`, `signing_identity.ts`),
+ * and P's scope is the scope the directive's provider declares. A principal is `<scope>:<subject>`,
+ * exactly its Zanzibar subject. Its first signer tuple lands one of two ways:
+ *
+ * - **Enrolled scope.** A principal holding `principalScope:<scope>#enroller` (the tenant's backend, or
+ *   the console hosting one) verified the provider's token OFF the ledger and writes
+ *   {@link enrollDevice}. The enroller is recorded as the tuple's `grantedBy`; no token, issuer or
+ *   `verifiedVia` provenance is law. {@link revokeDevice} is its mirror.
+ * - **Sovereign scope.** The principal is `<scope>:<sha256(root key)>` and certifies itself:
+ *   {@link sovereignSelfCertification} writes the founding tuple, marked
+ *   `nomos:selfCertifyingPrincipal = "true"` so the kernel admits it iff the signing key's sha256 is
+ *   the principal's subject.
+ *
+ * Every further device, either scope, is proof of possession: an active signer of P writes
+ * `enrollSigner` for the new key. A principal always revokes its own keys with `revokeSigner`.
+ *
+ * `enroller` is a framework-global relation on the framework object type `principalScope`, granted and
+ * revoked by an admin (`grantEnroller`/`revokeEnroller`, `workspaces.ts`) and copied into a child at
+ * birth exactly like `operator` (D15/D18: `readInheritedEnrollers` → `buildGenesisChain`).
+ */
+import { z } from "zod";
+import { directive, type RequirableDirective } from "../directive.js";
+import { query } from "../query.js";
+import { readFrameworkDeclaredRows } from "../read.js";
+import { relationType, self, user, key } from "../relation_schema.js";
+import { endorsementOf } from "../principal_evidence.js";
+import {
+  authenticatesWith,
+  consolePrincipals,
+  CONSOLE_PRINCIPAL_SCOPE,
+  custodianPrincipals,
+  CUSTODIAN_PRINCIPAL_SCOPE,
+  isAuthenticationProvider,
+  principalScopeOf,
+  principalsOf,
+  RESERVED_PROVIDER_SCOPES,
+  type SovereignProviderRef,
+} from "../member_authentication.js";
+import { PRINCIPAL_SCOPE_ENROLLER_RELATION } from "./governance_relations.js";
+import { RelationTuple, removeTuple, writeTuple } from "./relations.js";
+import { signerObject, SIGNER_RELATION } from "./signing_identity.js";
+
+/** The framework object type naming one provider scope: `principalScope:<scope>`. */
+export const PRINCIPAL_SCOPE_OBJECT_TYPE = "principalScope" as const;
+
+/** The Zanzibar object on which a scope's enrollers are seated. */
+export function principalScopeObject(scope: string): string {
+  return `${PRINCIPAL_SCOPE_OBJECT_TYPE}:${requireProviderScope(scope)}`;
+}
+
+const scopePattern = /^[A-Za-z][A-Za-z0-9._-]{0,127}$/;
+const sha256Hex = z.string().regex(/^[0-9a-f]{64}$/, "expected lowercase sha256 hex (a public key hash)");
+
+function requireProviderScope(scope: string): string {
+  if (typeof scope !== "string" || !scopePattern.test(scope) || RESERVED_PROVIDER_SCOPES.includes(scope)) {
+    throw new Error(`'${String(scope)}' is not a provider scope`);
+  }
+  return scope;
+}
+
+/** A provider scope in a payload: bounded, and never a framework subject type. */
+export const providerScopeField = z
+  .string()
+  .regex(scopePattern, "a provider scope is a bounded identifier")
+  .refine((scope) => !RESERVED_PROVIDER_SCOPES.includes(scope), "a reserved scope names no principals");
+
+/**
+ * The framework governance relations' subject classes (`workspace:self#operator`,
+ * `principalScope:<s>#enroller`): `user:` and `key:`, the console's enrolled principals
+ * (`console:<subject>`), and the framework's sovereign custodian principals (`custodian:<keyhash>`, the
+ * founding admin of a root born by token-free genesis). The framework cannot name a tenant's scopes — law
+ * is installed per domain (D21) and the framework's unit is composed with every tenant's — so the only
+ * provider scopes its own relations admit are the two the framework itself declares: the console's,
+ * whose principals are the operators who install law and the hosted enrollers that act for tenants
+ * (D18, D22), and the custodians'. Leaf-only: never a userset or wildcard.
+ */
+export const GOVERNANCE_SUBJECTS = Object.freeze([
+  user(),
+  key(),
+  principalsOf(consolePrincipals),
+  // Token-free genesis (D22): a root's founding admin is a sovereign custodian principal, and it is the
+  // root's first enroller and operator, so the framework's governance relations must admit it.
+  principalsOf(custodianPrincipals),
+]);
+
+/** The Zanzibar subject classes {@link GOVERNANCE_SUBJECTS} admits, as a predicate over one subject. */
+export function isGovernanceSubject(subject: string): boolean {
+  if (/^user:.+/.test(subject)) return true;
+  if (/^key:[0-9a-f]{64}$/.test(subject)) return true;
+  const scope = principalScopeOf(subject);
+  return scope === CONSOLE_PRINCIPAL_SCOPE || scope === CUSTODIAN_PRINCIPAL_SCOPE;
+}
+
+/** `principalScope:<scope>#enroller` — see {@link PRINCIPAL_SCOPE_ENROLLER_RELATION}. */
+export const principalScopeRelations = relationType(PRINCIPAL_SCOPE_OBJECT_TYPE)
+  // GLOBAL, like `workspace` and `identity`: the object is addressed by its bare type on every door.
+  .asGlobal()
+  .relation(PRINCIPAL_SCOPE_ENROLLER_RELATION, { rewrite: self(), allow: [...GOVERNANCE_SUBJECTS] });
+
+/**
+ * A governance grant names its subject exactly one way: a device key (`keyHash` → `key:<hash>`), a
+ * legacy user (`principal` → `user:<uid>`), or a console principal (`consolePrincipal`, the full
+ * `console:<subject>`).
+ */
+export const governanceSubjectFields = {
+  keyHash: sha256Hex.optional(),
+  principal: z.string().min(1).optional(),
+  consolePrincipal: z
+    .string()
+    .refine((value) => principalScopeOf(value) === CONSOLE_PRINCIPAL_SCOPE, "a console principal is console:<subject>")
+    .optional(),
+} as const;
+
+type GovernanceSubjectPayload = {
+  keyHash?: string | undefined;
+  principal?: string | undefined;
+  consolePrincipal?: string | undefined;
+};
+
+/** Exactly one subject form is present. */
+export function hasOneGovernanceSubject(payload: GovernanceSubjectPayload): boolean {
+  return [payload.keyHash, payload.principal, payload.consolePrincipal].filter((value) => !!value).length === 1;
+}
+
+/** The Zanzibar subject a governance grant names. Refuses anything but exactly one well-formed form. */
+export function governanceSubject(payload: GovernanceSubjectPayload): string {
+  if (!hasOneGovernanceSubject(payload)) {
+    throw new Error("a governance grant names exactly one of keyHash, principal or consolePrincipal");
+  }
+  if (payload.principal) return `user:${payload.principal}`;
+  if (payload.consolePrincipal) {
+    if (principalScopeOf(payload.consolePrincipal) !== CONSOLE_PRINCIPAL_SCOPE) {
+      throw new Error("a console principal is console:<subject>");
+    }
+    return payload.consolePrincipal;
+  }
+  if (!/^[0-9a-f]{64}$/.test(payload.keyHash ?? "")) throw new Error("keyHash is a lowercase sha256 hex");
+  return `key:${payload.keyHash}`;
+}
+
+/** The payload that names `subject` again — the inverse of {@link governanceSubject}, for birth seeding. */
+export function governanceSubjectPayload(subject: string): GovernanceSubjectPayload {
+  if (subject.startsWith("user:")) return { principal: subject.slice("user:".length) };
+  if (subject.startsWith("key:")) return { keyHash: subject.slice("key:".length) };
+  if (principalScopeOf(subject) === CONSOLE_PRINCIPAL_SCOPE) return { consolePrincipal: subject };
+  throw new Error(`'${subject}' is not a governance subject`);
+}
+
+function requirePrincipalOfScope(principal: string, scope: string): void {
+  if (principalScopeOf(principal) !== requireProviderScope(scope)) {
+    throw new Error(`principal-not-in-scope: '${principal}' is not a '${scope}:<subject>' principal`);
+  }
+}
+
+const enrollmentPayload = z
+  .object({
+    /** The principal's scope. The enroller is checked on `principalScope:<scope>`, so the plan refuses
+     *  a principal outside it: an enroller of one scope can never mint another scope's principal. */
+    scope: providerScopeField,
+    principal: z.string().min(1),
+    /** sha256 hex of the device's Ed25519 public key. */
+    keyHash: sha256Hex,
+  })
+  .strict()
+  .refine((p) => principalScopeOf(p.principal) === p.scope, {
+    message: "principal must be <scope>:<subject> of the named scope",
+    path: ["principal"],
+  });
+
+/**
+ * `enrollDevice { scope, principal, keyHash }` — an enroller of `scope` writes
+ * `identity:<principal>#signer@key:<keyHash>`: the device-bound session of an enrolled scope. The enroller
+ * verified the provider's ID token off the ledger (its OIDC `nonce` must be `keyHash`, and it is
+ * accepted once), so nothing of the provider lands here. `grantedBy` records the enroller.
+ */
+export const enrollDevice = directive("enrollDevice")
+  .ensures(RelationTuple)
+  .payload(enrollmentPayload)
+  .plan((p, ctx) => {
+    requirePrincipalOfScope(p.principal, p.scope);
+    return writeTuple({
+      object: signerObject(p.principal),
+      relation: SIGNER_RELATION,
+      subject: `key:${p.keyHash}`,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: String(ctx.clock().physical),
+    });
+  })
+  .requires(PRINCIPAL_SCOPE_ENROLLER_RELATION, {
+    objectFrom: { recordType: PRINCIPAL_SCOPE_OBJECT_TYPE, idField: "scope" },
+  });
+
+/**
+ * `revokeDevice { scope, principal, keyHash }` — an enroller of `scope` revokes one key of one of its
+ * scope's principals (remove-wins; later writes by that key are refused at their position). A principal
+ * always revokes its own keys itself with `revokeSigner`.
+ */
+export const revokeDevice = directive("revokeDevice")
+  .ensures(RelationTuple)
+  .payload(enrollmentPayload)
+  .plan((p, ctx) => {
+    requirePrincipalOfScope(p.principal, p.scope);
+    const at = String(ctx.clock().physical);
+    return removeTuple({
+      object: signerObject(p.principal),
+      relation: SIGNER_RELATION,
+      subject: `key:${p.keyHash}`,
+      grantedBy: ctx.principal().asAttribution(),
+      grantedAt: at,
+      revokedBy: ctx.principal().asAttribution(),
+      revokedAt: at,
+    });
+  })
+  .requires(PRINCIPAL_SCOPE_ENROLLER_RELATION, {
+    objectFrom: { recordType: PRINCIPAL_SCOPE_OBJECT_TYPE, idField: "scope" },
+  });
+
+/**
+ * The founding signer of a SOVEREIGN principal, certified by its own root key (D22). The directive
+ * authenticates with `provider`, so the kernel's ordinary rule already pins the captured principal to
+ * that sovereign scope; the `nomos:selfCertifyingPrincipal` marker adds the one self-certification
+ * rule — the signing key's sha256 is the principal's subject, and needs no prior signer — and the plan
+ * refuses any `keyHash` that is not that subject. The tuple it writes is
+ * `identity:<scope>:<keyHash>#signer@key:<keyHash>`.
+ *
+ * One directive per sovereign scope; `id` defaults to `certifySovereignPrincipal`.
+ */
+export function sovereignSelfCertification(
+  provider: SovereignProviderRef,
+  id = "certifySovereignPrincipal",
+): RequirableDirective<{ keyHash: string }> {
+  if (!isAuthenticationProvider(provider) || provider.kind !== "sovereign") {
+    throw new Error("sovereignSelfCertification takes a sovereign provider declared with authenticationProvider");
+  }
+  const scope = provider.scope;
+  return authenticatesWith(
+    directive(id)
+      .ensures(RelationTuple)
+      .payload(z.object({ keyHash: sha256Hex }).strict())
+      .plan((p, ctx) => {
+        const me = ctx.principal().asAuthoritySubject<string>("certify my sovereign identity with its own root key");
+        const principal = endorsementOf(me)?.principal ?? "";
+        if (principal !== `${scope}:${p.keyHash}`) {
+          throw new Error("sovereign-principal-is-its-root-key-hash");
+        }
+        return writeTuple({
+          object: signerObject(principal),
+          relation: SIGNER_RELATION,
+          subject: `key:${p.keyHash}`,
+          grantedBy: ctx.principal().asAttribution(),
+          grantedAt: String(ctx.clock().physical),
+        });
+      })
+      .selfCertifyingPrincipal(),
+    provider,
+  );
+}
+
+/** Every tuple of one relation name, across objects — the enroller seeding read. */
+export const relationTuplesByRelation = query("relationTuplesByRelation")
+  .key("relation")
+  .returns(RelationTuple);
+
+/** One inherited enroller grant: the scope and the subject holding it. */
+export interface InheritedEnroller {
+  readonly scope: string;
+  readonly subject: string;
+}
+
+/**
+ * ENROLLER INHERITANCE (D22, as D15 for `operator`): the parent's CURRENT active
+ * `principalScope:<scope>#enroller` tuples, read by the birthing plan and seated on the child by one
+ * `grantEnroller` genesis step each — copied once at birth, never a live dependency on the parent.
+ * Sorted by (scope, subject) so the recipe is a pure function of the tuple set.
+ */
+export function readInheritedEnrollers(): readonly InheritedEnroller[] {
+  const rows = readFrameworkDeclaredRows(relationTuplesByRelation, RelationTuple, {
+    relation: PRINCIPAL_SCOPE_ENROLLER_RELATION,
+  });
+  const prefix = `${PRINCIPAL_SCOPE_OBJECT_TYPE}:`;
+  const out: InheritedEnroller[] = [];
+  for (const row of rows) {
+    if (row.relation !== PRINCIPAL_SCOPE_ENROLLER_RELATION || !row.object?.startsWith(prefix)) continue;
+    const scope = row.object.slice(prefix.length);
+    const subjects = row.subjects as Record<string, { status?: string }> | undefined;
+    for (const [subject, leaf] of Object.entries(subjects ?? {})) {
+      if (leaf?.status === "active") out.push({ scope, subject });
+    }
+  }
+  return out.sort((a, b) =>
+    a.scope < b.scope ? -1 : a.scope > b.scope ? 1 : a.subject < b.subject ? -1 : a.subject > b.subject ? 1 : 0);
+}