@githolon/dsl 0.108.7 → 0.110.0

package/src/framework/receiving_group_recovery.ts

@@ -0,0 +1,314 @@
+// 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.
+
+/**
+ * RECEIVING-GROUP DEVICE RECOVERY — framework law, composed by the application's declaration.
+ *
+ * A verified person's receiving group is the framework's identity anchor. When the application
+ * declares `application.receivingGroup.recovery = "platform-identity-provider"`, the anchor is born
+ * with that posture (`receiving_group.ts`, the policy seed) and this module supplies the ONE recovery door that
+ * posture means: a replacement device, already seated on the attested parent platform by the ordinary
+ * `enrollFirstDevice` lane, asks the platform to re-seat it on the receiving group. Platform law derives
+ * both the target and the evidence from its own committed state (the user's current typed
+ * `SignerDelegation` and the platform's current typed `AuthProvider`); the host delivers a sealed effect
+ * and chooses nothing. The receiving group's own gate then proves the evidence against ITS birth record,
+ * ITS group facts and ITS selected posture before seating anything.
+ *
+ * Both halves live in the injected application-home domain, which runs on the platform workspace AND is
+ * installed into every receiving group at genesis, so the parent door and the child acceptor are one
+ * exported `Directive` pair in one law module (the compiler's exact-export rule).
+ *
+ * Provenance: this is the framework form of the door CO2 authored as tenant law
+ * (`co2_platform/auth_provider_epoch.ts`, `co2_home/auth_provider_epoch_accept.ts`,
+ * `auth_provider_authority.ts`). The composition of policy + signer seat + delegation + verifier epoch +
+ * parent-authority seat into ONE target transition is load-bearing: split into independently delivered
+ * effects, delivery order would become transport state rather than law.
+ */
+import { z } from "zod";
+import { directive, nomosImplementationDetail } from "../directive.js";
+import { intent } from "../intent.js";
+import {
+  AuthProvider,
+  AuthProviderCertificate,
+  AuthProviderKey,
+  authProvider,
+  authProviderCertificates,
+  authProviderConfiguration,
+  authProviderKeys,
+  readAuthProviderConfiguration,
+  writeAuthProviderConfiguration,
+} from "./auth_provider_law.js";
+// THE SHARED EPOCH ACCEPTOR + PARENT-AUTHORITY SEAT live in the framework's child-authentication law
+// (every business-born child adopts its parent's verifier epoch through the same door a receiving group
+// does); this module re-exports them under their historical names so the composed posture law is unchanged.
+import {
+  ACCEPT_PARENT_AUTH_PROVIDER_EPOCH_ID,
+  acceptParentAuthProviderEpoch,
+  acceptParentAuthProviderEpochEffect,
+  seatVerifiedBirthParentAuthority,
+  verifiedBirthAttestation,
+} from "./child_authentication.js";
+import {
+  BIRTH_ATTESTATION_ID,
+  BirthAttestation,
+  DEFAULT_RECEIVING_GROUP_POLICY,
+  PLATFORM_IDENTITY_PROVIDER_RECOVERY,
+  RECEIVING_GROUP_ID,
+  RECEIVING_GROUP_POLICY_ID,
+  ReceivingGroup,
+  ReceivingGroupPolicy,
+  type ReceivingGroupRecoveryPolicy,
+  writeReceivingGroupPolicy,
+} from "./receiving_group.js";
+import { RelationTuple, writeTuple } from "./relations.js";
+import {
+  SIGNER_RELATION,
+  SignerDelegation,
+  readSignerDelegationRecoveryEvidence,
+  signerDelegationByUser,
+  signerDelegationEvidenceIsRetained,
+  signerDelegationRecoveryEvidence,
+  signerObject,
+  writeSignerDelegationRecoveryEvidence,
+} from "./signing_identity.js";
+import { readRef, readSet, workspaceInvariant } from "./workspace_invariant.js";
+
+/** Wire ids — framework-internal, obscure on purpose (the 7c1f5e suffix convention). */
+export const RECOVER_RECEIVING_GROUP_DEVICE_ID = "nomosInternalRecoverReceivingGroupDevice7c1f5e";
+export const ACCEPT_RECEIVING_GROUP_DEVICE_RECOVERY_ID = "nomosInternalAcceptReceivingGroupDeviceRecovery7c1f5e";
+export { ACCEPT_PARENT_AUTH_PROVIDER_EPOCH_ID, verifiedBirthAttestation };
+
+/** The exact typed parent disclosure used to recover a receiving-group device. Neither the host nor
+ * the caller supplies verifier members: platform law reads both values from its committed state. */
+export const receivingGroupDeviceRecoveryEvidence = z
+  .object({
+    delegation: signerDelegationRecoveryEvidence,
+    authProvider: authProviderConfiguration,
+  })
+  .strict();
+export type ReceivingGroupDeviceRecoveryEvidence = z.infer<typeof receivingGroupDeviceRecoveryEvidence>;
+
+// ── CHILD SIDE: the receiving group's own consequences ────────────────────────────────────────────
+
+/** Re-seat the selected posture for a group born under the untouched framework default. Genesis seeds
+ * the declared posture directly; this exists for anchors born before the application declared one.
+ * ONE module-level singleton (the only posture with a door is the attested parent), so every evaluation
+ * of the composed law resolves the same declaration object — the compiler registers these singletons as
+ * the application-home domain's declaration exports exactly like `child_authentication.ts`. */
+export const setReceivingGroupRecoveryPosture = nomosImplementationDetail(
+  directive("nomosInternalSetReceivingGroupRecoveryPosture7c1f5e")
+    .ensures(ReceivingGroupPolicy)
+    .payload(z.object({ setAt: z.string().min(1) }).strict())
+    .plan((p) => writeReceivingGroupPolicy({ setAt: p.setAt, recovery: PLATFORM_IDENTITY_PROVIDER_RECOVERY })),
+);
+
+export const seatRecoveredDevice = nomosImplementationDetail(
+  directive("nomosInternalSeatRecoveredReceivingGroupDevice7c1f5e")
+    .ensures(RelationTuple)
+    .payload(receivingGroupDeviceRecoveryEvidence)
+    .plan(({ delegation }) =>
+      writeTuple({
+        object: signerObject(delegation.user),
+        relation: SIGNER_RELATION,
+        subject: delegation.deviceKeySubject,
+        grantedBy: `workspace:${delegation.certificate.parentId}`,
+        grantedAt: delegation.enrolledAt,
+        ...(delegation.certificate.verifiedVia === undefined
+          ? {}
+          : { verifiedVia: delegation.certificate.verifiedVia }),
+        ...(delegation.certificate.epoch === undefined
+          ? {}
+          : { validFromEpoch: delegation.certificate.epoch }),
+      }),
+    ),
+);
+
+/** A recovered key must carry the parent's typed delegation certificate too, otherwise a later child
+ * birth combines a certificate signed by the recovered device with the group's original-device lineage
+ * and fails the offline chain walk. */
+export const adoptRecoveryDelegation = nomosImplementationDetail(
+  directive("nomosInternalAdoptRecoveryDelegation7c1f5e")
+    .ensures(SignerDelegation)
+    .payload(receivingGroupDeviceRecoveryEvidence)
+    .plan(({ delegation }) => writeSignerDelegationRecoveryEvidence(delegation)),
+);
+
+export const adoptRecoveryAuthProvider = nomosImplementationDetail(
+  directive("nomosInternalAdoptRecoveryAuthProvider7c1f5e")
+    .ensures(AuthProvider)
+    .payload(receivingGroupDeviceRecoveryEvidence)
+    .plan(({ authProvider: configuration }) => writeAuthProviderConfiguration(configuration))
+    .alsoEnsuresMany(AuthProviderKey)
+    .alsoEnsuresMany(AuthProviderCertificate),
+);
+
+/** The child-owned gate: the evidence must match THIS group's principal, name and verified birth, be
+ * delivered by THAT birth's parent, cite the parent's current provider issuer, and the group must be
+ * either untouched-birth-default or already the platform posture. */
+function receivingGroupDeviceRecoveryFollowsPosture(posture: ReceivingGroupRecoveryPolicy) {
+  return workspaceInvariant("ReceivingGroupDeviceRecoveryFollowsPosture")
+    .on(ACCEPT_RECEIVING_GROUP_DEVICE_RECOVERY_ID)
+    .reads(
+      readSet(
+        readRef("group", ReceivingGroup).at(RECEIVING_GROUP_ID),
+        readRef("policy", ReceivingGroupPolicy).at(RECEIVING_GROUP_POLICY_ID),
+        readRef("birth", BirthAttestation).at(BIRTH_ATTESTATION_ID),
+      ),
+    )
+    .declassify(
+      "device recovery deliberately reveals only whether the receiving group selected its attested parent identity provider",
+    )
+    .assert(({ group, policy, birth }, ctx) => {
+      const evidence = ctx?.intent as ReceivingGroupDeviceRecoveryEvidence | undefined;
+      const delegation = evidence?.delegation;
+      const certificate = delegation?.certificate;
+      const provider = evidence?.authProvider;
+      const untouchedBirthDefault =
+        policy?.recovery === DEFAULT_RECEIVING_GROUP_POLICY.recovery &&
+        typeof policy.setAt === "string" &&
+        typeof group?.bornAt === "string" &&
+        policy.setAt === group.bornAt;
+      const alreadySelected = policy?.recovery === posture;
+      if (!untouchedBirthDefault && !alreadySelected) {
+        return { reject: "receiving-group-recovery-posture-is-neither-birth-default-nor-declared" };
+      }
+      if (
+        typeof group?.principal !== "string" ||
+        typeof group.workspaceName !== "string" ||
+        delegation === undefined ||
+        certificate === undefined ||
+        provider === undefined ||
+        birth === undefined ||
+        delegation.user !== group.principal ||
+        certificate.founder !== group.principal ||
+        certificate.child !== group.workspaceName ||
+        certificate.verified !== true ||
+        certificate.parentId.length === 0 ||
+        birth.child !== group.workspaceName ||
+        birth.founder !== group.principal ||
+        birth.verified !== "true" ||
+        birth.parentId !== certificate.parentId ||
+        ctx?.principal !== `workspace:${certificate.parentId}` ||
+        certificate.verifiedVia !== provider.issuer ||
+        certificate.idpToken === undefined ||
+        certificate.capturedClock === undefined
+      ) {
+        return { reject: "receiving-group-device-recovery-evidence-mismatch" };
+      }
+      return { accept: true };
+    });
+}
+
+// ── PARENT SIDE: the platform's door ──────────────────────────────────────────────────────────────
+
+function currentRecoveryEvidence(user: string, deviceKeySubject?: string) {
+  const delegation = readSignerDelegationRecoveryEvidence(user, deviceKeySubject);
+  if (delegation === undefined) {
+    throw new Error(`receiving-group recovery requires the platform's current typed SignerDelegation for '${user}'`);
+  }
+  const provider = readAuthProviderConfiguration();
+  if (provider === undefined) {
+    throw new Error("receiving-group recovery requires the platform's current typed AuthProvider");
+  }
+  if (
+    delegation.certificate.founder !== user ||
+    delegation.certificate.verified !== true ||
+    delegation.certificate.parentId.length === 0 ||
+    delegation.certificate.verifiedVia !== provider.issuer ||
+    delegation.certificate.idpToken === undefined ||
+    delegation.certificate.capturedClock === undefined
+  ) {
+    throw new Error(
+      "receiving-group recovery found a delegation which is not exact current platform identity-provider evidence",
+    );
+  }
+  return receivingGroupDeviceRecoveryEvidence.parse({ delegation, authProvider: provider });
+}
+
+export const acceptReceivingGroupDeviceRecovery = nomosImplementationDetail(
+  intent(ACCEPT_RECEIVING_GROUP_DEVICE_RECOVERY_ID)
+    .contract({ accepts: receivingGroupDeviceRecoveryEvidence })
+    // Selecting the posture and applying the recovery evidence are ONE target-workspace transition.
+    .directs(setReceivingGroupRecoveryPosture, ({ delegation }) => ({ setAt: String(delegation.enrolledAt) }))
+    .directs(seatRecoveredDevice, (evidence) => evidence)
+    .directs(adoptRecoveryDelegation, (evidence) => evidence)
+    .directs(adoptRecoveryAuthProvider, (evidence) => evidence)
+    .directs(seatVerifiedBirthParentAuthority, () => ({}))
+    .acceptsVerifiedBirthParentRecoveryEffect()
+    .atomically(),
+);
+
+/** The replacement device authors on the platform, where its exact key is already enrolled. */
+export const recoverReceivingGroupDevice = nomosImplementationDetail(
+  intent(RECOVER_RECEIVING_GROUP_DEVICE_ID)
+    .contract({
+      accepts: z.object({
+        user: z.string().min(1),
+        deviceKeySubject: z.string().regex(/^key:[0-9a-f]{64}$/).optional(),
+      }).strict(),
+    })
+    .reads(signerDelegationByUser, authProvider, authProviderKeys, authProviderCertificates)
+    .directsWorkspace(acceptReceivingGroupDeviceRecovery, {
+      workspace: ({ user, deviceKeySubject }) =>
+        currentRecoveryEvidence(user, deviceKeySubject).delegation.certificate.child,
+      payload: ({ user, deviceKeySubject }) => currentRecoveryEvidence(user, deviceKeySubject),
+    })
+    .directsWorkspace(acceptParentAuthProviderEpoch, {
+      workspace: ({ user, deviceKeySubject }) =>
+        currentRecoveryEvidence(user, deviceKeySubject).delegation.certificate.child,
+      payload: ({ user, deviceKeySubject }) => currentRecoveryEvidence(user, deviceKeySubject).authProvider,
+    })
+    .authenticatesWithEnrolledDevice()
+    .atomically(),
+);
+
+/** A device may request recovery only for its own authenticated identity. */
+export const recoverReceivingGroupDeviceBindsPrincipal = workspaceInvariant(
+  "RecoverReceivingGroupDeviceBindsPrincipal",
+)
+  .on(RECOVER_RECEIVING_GROUP_DEVICE_ID)
+  .reads(readSet())
+  .assert((_snapshots, ctx) =>
+    ctx?.principal === (ctx?.intent as { user?: unknown } | undefined)?.user
+      ? { accept: true }
+      : { reject: "receiving-group-device-recovery-must-bind-authenticated-user" },
+  );
+
+/**
+ * The recovery law an application composes when its declared posture is the attested parent identity
+ * provider. Returned as one export map so the application-home policy law can merge it exactly like its
+ * other `__nomos_*` members; every member is presentation-internal.
+ */
+export function receivingGroupRecoveryLaw(posture: ReceivingGroupRecoveryPolicy) {
+  if (posture !== PLATFORM_IDENTITY_PROVIDER_RECOVERY) {
+    throw new Error(
+      `receivingGroupRecoveryLaw: posture '${posture}' has no platform recovery door; only ` +
+        `'${PLATFORM_IDENTITY_PROVIDER_RECOVERY}' re-seats a device through the attested parent`,
+    );
+  }
+  return {
+    __nomos_receivingGroupDeviceRecoveryEvidence: receivingGroupDeviceRecoveryEvidence,
+    __nomos_verifiedBirthAttestation: verifiedBirthAttestation,
+    __nomos_setReceivingGroupRecoveryPosture: setReceivingGroupRecoveryPosture,
+    // `seatRecoveredDevice` rides ONLY the acceptor's step closure (as `child_authentication.ts` carries its
+    // gated acceptor effect): the compiler infers the framework RelationTuple bookkeeping onto an exported
+    // tuple-writing directive as a fresh object, so a second export slot would resolve the one step to two
+    // declarations (`NMS-GRAPH-001`).
+    __nomos_adoptRecoveryDelegation: adoptRecoveryDelegation,
+    __nomos_adoptRecoveryAuthProvider: adoptRecoveryAuthProvider,
+    __nomos_acceptParentAuthProviderEpochEffect: acceptParentAuthProviderEpochEffect,
+    __nomos_seatVerifiedBirthParentAuthority: seatVerifiedBirthParentAuthority,
+    __nomos_acceptReceivingGroupDeviceRecovery: acceptReceivingGroupDeviceRecovery,
+    __nomos_acceptParentAuthProviderEpoch: acceptParentAuthProviderEpoch,
+    __nomos_receivingGroupDeviceRecoveryFollowsPosture: receivingGroupDeviceRecoveryFollowsPosture(posture),
+    __nomos_receivingGroupDeviceRecoveryRetainsEvidence: signerDelegationEvidenceIsRetained(
+      "ReceivingGroupDeviceRecoveryRetainsEvidence",
+      ACCEPT_RECEIVING_GROUP_DEVICE_RECOVERY_ID,
+      "delegation.user",
+    ),
+    __nomos_recoverReceivingGroupDevice: recoverReceivingGroupDevice,
+    __nomos_recoverReceivingGroupDeviceBindsPrincipal: recoverReceivingGroupDeviceBindsPrincipal,
+  };
+}

package/src/framework/relations.ts

@@ -211,20 +211,16 @@ export const RelationshipSubjectValue = valueObject("RelationshipSubject", {
   ownedCustody: OwnedCustodyValue.optional(),
 });
 
-// Historical RelationTuple law declared this map value as `t.json()`, but the
-// kernel has always admitted and stored only the nominal RelationshipSubject
-// palette for this framework field. Keep that exact prior declaration as the
-// source of the explicit evolution edge: this is a type-disclosure refinement
-// of existing structured custody, not a JSON parser or a business-data cast.
-const LegacyRelationshipSubjects = t.map(t.json()).merge(MapOf(Lww));
-
 export const RelationTuple = aggregate("RelationTuple", {
   object: t.string().merge(Lww),
   relation: t.string().merge(Lww),
   subjects: t
     .map(RelationshipSubjectValue.field())
     .merge(MapOf(Lww))
-    .evolvesFrom(LegacyRelationshipSubjects),
+    // Historical metadata called this leaf JSON, although the kernel's relation
+    // gate already required RelationshipSubject. Declare that exact disclosure
+    // transition; this does not permit arbitrary tenant JSON-to-object narrowing.
+    .evolvesFrom(t.map(t.json()).merge(MapOf(Lww))),
 }).public();
 export type RelationTupleHandle = typeof RelationTuple;