@githolon/dsl 0.7.0 → 0.8.0

package/src/framework/rbac.ts

@@ -1,418 +0,0 @@
-// 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} on V8 + WASI-shim, byte-identical everywhere.  V8 = portability; the one
-// wasm = determinism.  No native, no wasmtime, no 2nd artifact, no domain-JS on bare V8.
-// If a file isn't this / hosting this / authoring for this / proving this — it's gone.
-
-/**
- * framework/rbac.ts — the FRAMEWORK RBAC mechanism (tenant-agnostic).
- *
- * ── Why this module exists (the framework↔tenant line) ───────────────────────
- * Multi-layer RBAC role-bindings are framework MECHANISM, not tenant content. The
- * kernel ships the engine (`identity::authz` — `PermissionState::bindings_for` +
- * `effective_caps_for` + chain delegation + captured-deps) and the one shared
- * `admit` gate resolves the DECLARED `.requires(cap, scopeFrom)` pre-condition
- * against the folded permission projection. A tenant should therefore NOT
- * re-implement grant/revoke/delegate — it should DECLARE its roles→capabilities
- * (a `RoleCatalogue`) and its resource vocabulary, then USE these framework
- * primitives to author the binding-leaf writes.
- *
- * This module is the DSL surface for that mechanism:
- *   • `roleBindingSchema(resourceTypes)` — the stored binding-leaf shape (the
- *     EXACT JSON the kernel `identity::authz::RoleBinding` parses out of the
- *     `UserPermission.permissions` map);
- *   • `userPermissionAggregate(resourceTypes)` — the per-user aggregate shape +
- *     the `userPermissionsInstanceId`/`permissionId` deterministic id rules
- *     (`user-permissions-<userId>`, `perm-<userId>-<resourceType>-<resourceId>`);
- *   • `grant` / `revoke` / `delegate` / `revokeDelegation` — the four primitive
- *     PLAN BUILDERS. Each takes a `scope = [resourceType, resourceId]` (the
- *     framework's universal scope shape) + the actor/role/provenance and returns
- *     the `PlannedOp[]` that write the SAME binding leaf the authz engine reads.
- *   • `roleCatalogue(roles)` — the declaration helper a tenant uses to declare its
- *     roles→capabilities (the `RoleCatalogue` the kernel resolves a `role` string
- *     against; opaque to the framework — the framework provides the SHAPE, the
- *     tenant the CONTENT).
- *
- * ── CRITICAL — the kernel-read wire shape is FROZEN (`authz.rs` reads it) ──────
- * `identity::authz::PermissionState::bindings_for` reads JSON `RoleBinding` leaves
- * out of `UserPermission.permissions` (a `MapOf`, keyed
- * `user-permissions-<userId>`). The AUTHZ-RELEVANT fields the kernel parses are
- * frozen — `permissionId / userId / resourceType / resourceId / role / status /
- * grantedBy / grantedAt`, the revocation provenance (`revokedBy / revokedAt /
- * revocationReason`), and the OPTIONAL delegation fields (`delegator / attenuation
- * / expires`) which the kernel serde-defaults so a plain grant leaf is unchanged.
- * The OPTIONAL book-keeping (`displayName / lastViewed / resourceCount`) is NOT in
- * the kernel's `RoleBinding` struct — serde drops unknown leaf fields — so it is
- * invisible to authz and free to use framework-generic names (`resourceCount` is
- * the tenant-agnostic book-keeping count; a tenant maps its own domain noun onto
- * it at the directive surface). This is a refactor of WHO authors the leaf, NOT a
- * change to any field the kernel reads.
- */
-import { z } from "zod";
-import { aggregate, instance, type AggregateHandle } from "../aggregate.js";
-import { t } from "../fields.js";
-import { Lww, MapOf } from "../drivers.js";
-import { set, setEntry, type PlannedOp } from "../ops.js";
-
-/** Permission lifecycle — the framework binding-status vocabulary. */
-export const PERMISSION_STATUSES = ["active", "revoked", "suspended"] as const;
-export type PermissionStatus = (typeof PERMISSION_STATUSES)[number];
-
-/**
- * The framework binding-leaf schema, parameterised over a tenant's resource-type
- * vocabulary. A binding is the `(actor, role, scope)` triple from
- * identity-access §"Multi-layer RBAC", scope = `(resourceType, resourceId)`, plus
- * provenance, optional book-keeping, and the optional delegation fields. This
- * lowers to ONE JSON Str leaf (the kernel stores Str|Int leaves only — gap G2).
- *
- * `resourceTypes` is the tenant's enum; the framework does not fix it. The rest of
- * the shape is framework-fixed because the kernel `authz.rs` `RoleBinding` parses
- * it field-for-field.
- */
-export function roleBindingSchema<const T extends readonly [string, ...string[]]>(
-  resourceTypes: T,
-) {
-  return z.object({
-    permissionId: z.string(),
-    userId: z.string(),
-    // scope = (resourceType, resourceId), the org→workspace→resource address.
-    resourceType: z.enum(resourceTypes),
-    resourceId: z.string(),
-    // role within that scope (a role = a capability set; resolved by the kernel
-    // authz slice against the tenant `RoleCatalogue`; opaque string here).
-    role: z.string(),
-    status: z.enum(PERMISSION_STATUSES),
-    grantedBy: z.string(),
-    grantedAt: z.string(),
-    // book-keeping (tenant `updatePermissionMetadata`): all optional.
-    displayName: z.string().optional(),
-    lastViewed: z.string().optional(),
-    resourceCount: z.number().int().optional(),
-    // revocation provenance, set when status flips to "revoked".
-    revokedBy: z.string().optional(),
-    revokedAt: z.string().optional(),
-    revocationReason: z.string().optional(),
-    // ── DELEGATION (identity-access §"delegated authority") ──
-    // `delegator` set ⇒ this binding is a DELEGATION (actor A handed a capability
-    // subset down to `userId`). Honoured only if A held those caps at the
-    // evaluation point-in-time (kernel `effective_caps_for` recurses to a
-    // delegator-less root). All three OPTIONAL so a plain grant leaf is unchanged.
-    delegator: z.string().optional(),
-    // the capability subset handed down (the attenuation ceiling).
-    attenuation: z.array(z.string()).optional(),
-    // point-in-time expiry (ISO/HLC string mirror).
-    expires: z.string().optional(),
-  });
-}
-
-/**
- * The generic framework binding-leaf type. A tenant narrows `resourceType` via its
- * own `roleBindingSchema(RESOURCE_TYPES)`; the framework primitives below accept a
- * plain `string` resourceType (the tenant's enum is a subtype) so the mechanism is
- * tenant-agnostic.
- */
-export type FrameworkRoleBinding = {
-  permissionId: string;
-  userId: string;
-  resourceType: string;
-  resourceId: string;
-  role: string;
-  status: PermissionStatus;
-  grantedBy: string;
-  grantedAt: string;
-  displayName?: string;
-  lastViewed?: string;
-  resourceCount?: number;
-  revokedBy?: string;
-  revokedAt?: string;
-  revocationReason?: string;
-  delegator?: string;
-  attenuation?: string[];
-  expires?: string;
-};
-
-/**
- * The per-user permissions aggregate SHAPE — framework mechanism. Wire id
- * `UserPermission` matches the live aggregate type the kernel folds and
- * `bindings_for` reads. Multi-instance, keyed `user-permissions-<userId>`.
- *
- *  - userId        Lww (identity)
- *  - permissions   MapOf(Lww) — the map-of-driven role-binding entries; each value
- *                  is a JSON-encoded binding (a `t.json` Str leaf), merged per-key
- *                  by Lww (the closest-expressible map driver — gap G1)
- *  - lastViewedAt  Lww (aggregate-level "last touched")
- */
-export const userPermissionAggregate = aggregate("UserPermission", {
-  userId: t.string().merge(Lww),
-  permissions: t.map(t.json()).merge(MapOf(Lww)),
-  // The grant/ensure primitive folds ONLY userId + a permissions entry (writeBinding),
-  // never lastViewedAt — a freshly-ensured per-user record lacks it — OPTIONAL on
-  // the read type (read-decode gap).
-  lastViewedAt: t.string().merge(Lww).optional(),
-});
-export type UserPermissionAggregateHandle = typeof userPermissionAggregate;
-
-/**
- * Deterministic per-user aggregate instance id — `user-permissions-<userId>`.
- * Reproduces the Dart aggregate-id rule so two users' bindings fold into two
- * distinct aggregates (never colliding on the shared type) and replay is stable.
- */
-export function userPermissionsInstanceId(userId: string): string {
-  return `user-permissions-${userId}`;
-}
-
-/**
- * Deterministic permission-id (map key) — `perm-<userId>-<resourceType>-<resourceId>`.
- * Reproduces the Dart `execute()` rule so the same (user, scope) always maps to the
- * same map key (kills the dup-grant re-dispatch class).
- */
-export function permissionId(input: {
-  userId: string;
-  resourceType: string;
-  resourceId: string;
-}): string {
-  return `perm-${input.userId}-${input.resourceType}-${input.resourceId}`;
-}
-
-/**
- * A framework scope: `[resourceType, resourceId]`. This is the universal scope the
- * framework `grant`/`revoke`/`delegate` primitives take and the same shape a
- * directive's `.requires(cap, p => [resourceType, resourceId])` derives so the
- * authz gate checks the actor holds the capability at a covering scope.
- */
-export type Scope = readonly [resourceType: string, resourceId: string];
-
-/** Bind the per-user aggregate handle to a concrete user instance. */
-function userInstance(userId: string) {
-  return instance(userPermissionAggregate, userPermissionsInstanceId(userId));
-}
-
-/**
- * Strip `undefined`-valued keys so the JSON leaf is byte-stable (no `"k":null`,
- * no `"k":undefined`-dropped key carrying a slot). Returns a `FrameworkRoleBinding`
- * — the omitted-when-undefined optionals are exactly the schema's `.optional()`s.
- */
-function compact(obj: Record<string, unknown>): FrameworkRoleBinding {
-  const out: Record<string, unknown> = {};
-  for (const [k, v] of Object.entries(obj)) {
-    if (v !== undefined) out[k] = v;
-  }
-  return out as FrameworkRoleBinding;
-}
-
-/** Common fields every grant-family primitive consumes. */
-interface BindingInput {
-  userId: string;
-  scope: Scope;
-  role: string;
-  grantedBy: string;
-  grantedAt: string;
-  displayName?: string | undefined;
-}
-
-/**
- * Build a role-binding leaf for one (user, scope) pair. The single place the
- * framework constructs the wire leaf the kernel `authz.rs` reads — every primitive
- * routes through here so the shape can never drift.
- */
-function buildBinding(
-  p: BindingInput & {
-    status: PermissionStatus;
-    revokedBy?: string | undefined;
-    revokedAt?: string | undefined;
-    revocationReason?: string | undefined;
-    delegator?: string | undefined;
-    attenuation?: string[] | undefined;
-    expires?: string | undefined;
-    lastViewed?: string | undefined;
-    resourceCount?: number | undefined;
-  },
-): { pid: string; binding: FrameworkRoleBinding } {
-  const [resourceType, resourceId] = p.scope;
-  const pid = permissionId({ userId: p.userId, resourceType, resourceId });
-  const binding = compact({
-    permissionId: pid,
-    userId: p.userId,
-    resourceType,
-    resourceId,
-    role: p.role,
-    status: p.status,
-    grantedBy: p.grantedBy,
-    grantedAt: p.grantedAt,
-    displayName: p.displayName,
-    lastViewed: p.lastViewed,
-    resourceCount: p.resourceCount,
-    revokedBy: p.revokedBy,
-    revokedAt: p.revokedAt,
-    revocationReason: p.revocationReason,
-    delegator: p.delegator,
-    attenuation: p.attenuation,
-    expires: p.expires,
-  });
-  return { pid, binding };
-}
-
-/**
- * Lower a built binding to the `PlannedOp[]` for a per-user aggregate. `ensure`
- * (the default) also writes the `userId` Set so the first grant materialises the
- * aggregate (matching `EnsuresEntityPayload`); a plain status-flip (revoke) omits
- * it (`ensure = false`) since the aggregate already exists.
- */
-function writeBinding(
-  userId: string,
-  pid: string,
-  binding: FrameworkRoleBinding,
-  ensure = true,
-): PlannedOp[] {
-  const upa = userInstance(userId);
-  const ops: PlannedOp[] = [];
-  if (ensure) ops.push(set(upa, "userId", userId));
-  ops.push(setEntry(upa, "permissions", pid, JSON.stringify(binding)));
-  return ops;
-}
-
-/**
- * grant — the framework PRIMITIVE: write one ACTIVE role-binding for `userId` at
- * `scope`. The collapse target of a tenant grant-family directive (the scope's
- * `resourceType` is fixed per tenant directive). Ensures the per-user aggregate.
- */
-export function grant(p: BindingInput): PlannedOp[] {
-  const { pid, binding } = buildBinding({ ...p, status: "active" });
-  return writeBinding(p.userId, pid, binding, true);
-}
-
-/**
- * revoke — the framework PRIMITIVE: flip the binding at `scope` to `status:revoked`
- * (an Lww write over the SAME map entry — gap G1: ideally remove-wins). Re-authors
- * the full leaf since a JSON leaf is replaced wholesale by Lww.
- */
-export function revoke(
-  p: BindingInput & {
-    revokedBy: string;
-    revokedAt: string;
-    reason?: string | undefined;
-  },
-): PlannedOp[] {
-  const { pid, binding } = buildBinding({
-    ...p,
-    status: "revoked",
-    revokedBy: p.revokedBy,
-    revokedAt: p.revokedAt,
-    revocationReason: p.reason,
-  });
-  return writeBinding(p.userId, pid, binding, false);
-}
-
-/**
- * delegate — the framework PRIMITIVE: actor `delegatedBy` (A) hands a capability
- * subset down to `userId` (B) at `scope`, writing a `delegator`-stamped, attenuated
- * ACTIVE binding into B's per-user map. Mirrors `grant`'s write shape but the leaf
- * carries `delegator`/`attenuation`/`expires`. Self-authenticating (A signs the
- * authoring intent); honoured only if A held the caps point-in-time (kernel
- * `effective_caps_for`). Ensures B's aggregate.
- */
-export function delegate(p: {
-  userId: string;
-  scope: Scope;
-  role: string;
-  attenuation: string[];
-  delegatedBy: string;
-  grantedAt: string;
-  expires?: string | undefined;
-  displayName?: string | undefined;
-}): PlannedOp[] {
-  const { pid, binding } = buildBinding({
-    userId: p.userId,
-    scope: p.scope,
-    role: p.role,
-    grantedBy: p.delegatedBy,
-    grantedAt: p.grantedAt,
-    status: "active",
-    delegator: p.delegatedBy,
-    attenuation: p.attenuation,
-    expires: p.expires,
-    displayName: p.displayName,
-  });
-  return writeBinding(p.userId, pid, binding, true);
-}
-
-/**
- * revokeDelegation — the framework PRIMITIVE: flip a delegated binding to revoked
- * (an Lww write over the SAME entry, like `revoke`, but carrying the
- * `delegator`/`attenuation` provenance). Revoking the DELEGATOR's ROOT binding (a
- * plain `revoke`) is the load-bearing case — the chained delegate loses its caps
- * point-in-time via the fold with NO propagation; this is the symmetric surface
- * for revoking a delegated leaf directly. Mutates (the aggregate exists).
- */
-export function revokeDelegation(p: {
-  userId: string;
-  scope: Scope;
-  role: string;
-  attenuation: string[];
-  delegatedBy: string;
-  grantedAt: string;
-  revokedBy: string;
-  revokedAt: string;
-  reason?: string | undefined;
-}): PlannedOp[] {
-  const { pid, binding } = buildBinding({
-    userId: p.userId,
-    scope: p.scope,
-    role: p.role,
-    grantedBy: p.delegatedBy,
-    grantedAt: p.grantedAt,
-    status: "revoked",
-    delegator: p.delegatedBy,
-    attenuation: p.attenuation,
-    revokedBy: p.revokedBy,
-    revokedAt: p.revokedAt,
-    revocationReason: p.reason,
-  });
-  return writeBinding(p.userId, pid, binding, false);
-}
-
-/**
- * updateMetadata — the framework PRIMITIVE for the book-keeping write
- * (`lastViewed`/`resourceCount`/`displayName`) on an existing ACTIVE binding, plus the
- * aggregate-level `lastViewedAt`. NOT authz (it never changes role/scope/status) —
- * a tenant wraps it as its own directive (e.g. `updatePermissionMetadata`).
- */
-export function updateMetadata(
-  p: BindingInput & {
-    lastViewed?: string | undefined;
-    resourceCount?: number | undefined;
-  },
-): PlannedOp[] {
-  const { pid, binding } = buildBinding({
-    ...p,
-    status: "active",
-    lastViewed: p.lastViewed,
-    resourceCount: p.resourceCount,
-  });
-  const ops = writeBinding(p.userId, pid, binding, false);
-  if (p.lastViewed !== undefined) {
-    ops.push(set(userInstance(p.userId), "lastViewedAt", p.lastViewed));
-  }
-  return ops;
-}
-
-/**
- * A tenant `RoleCatalogue` declaration: `role → capability set` (the directive
- * names a role grants). This is the SHAPE the kernel `identity::authz::RoleCatalogue`
- * (a `BTreeMap<String, BTreeSet<Capability>>`) resolves a binding's `role` string
- * against. The framework provides the declaration HELPER + type; the tenant
- * supplies the CONTENT (its roles, its capabilities). Capabilities are directive
- * names (a directive's name IS its capability — the `.requires(cap)` convention).
- */
-export type RoleCatalogue = Readonly<Record<string, readonly string[]>>;
-
-/**
- * Declare a tenant `RoleCatalogue`. Pure passthrough that brands the shape + freezes
- * it so a tenant declares `roleCatalogue({ siteAdmin: ["grantSiteAccess", …] })`
- * once and the framework/kernel resolve a `role` against it. Tenant-agnostic: the
- * framework fixes the SHAPE, never the roles.
- */
-export function roleCatalogue<const C extends RoleCatalogue>(roles: C): C {
-  return Object.freeze({ ...roles }) as C;
-}