attention-manifest-protocol 0.4.0 → 0.4.2

package/lib/governance/signing.js

@@ -0,0 +1,241 @@
+import { generateSigningKey } from "../manifest/sign.js";
+import { canonical } from "../semantic/canonical.js";
+import { GovernanceError } from "./types.js";
+const Encoder = new TextEncoder();
+const toBase64Url = (bytes) => {
+    const view = new Uint8Array(bytes);
+    let binary = "";
+    for (let index = 0; index < view.length; index += 1) {
+        binary += String.fromCharCode(view[index]);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+};
+const fromBase64Url = (text) => {
+    const padded = text.replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 ? "=".repeat(4 - (padded.length % 4)) : "";
+    const binary = atob(padded + pad);
+    return Uint8Array.from(binary, (char) => char.charCodeAt(0));
+};
+/**
+ * Generic canonical-value signatures for transport envelopes and audit
+ * checkpoints. The governance-specific functions below bind a digest to a
+ * subject; these helpers only sign the canonical JSON of `value`.
+ */
+export const signCanonicalValue = async (value, key) => {
+    const signature = await crypto.subtle.sign("Ed25519", key.privateKey, Encoder.encode(canonical(value)));
+    return toBase64Url(signature);
+};
+export const verifyCanonicalValue = async (value, signature, publicKey) => crypto.subtle.verify("Ed25519", publicKey, fromBase64Url(signature), Encoder.encode(canonical(value)));
+export class GovernanceKeyring {
+    keys = new Map();
+    revoked = new Set();
+    revokedKids = new Set();
+    onEvent;
+    constructor(options = {}) {
+        this.onEvent = options.onEvent;
+    }
+    emit(action, signer, at, kid) {
+        this.onEvent?.({
+            action,
+            signer,
+            ...(kid === (void 0) ? {} : { kid }),
+            at,
+        });
+    }
+    add(signer, publicKey, record = {}) {
+        const existing = this.keys.get(signer) ?? [];
+        existing.push({
+            key: publicKey,
+            ...(record.kid === (void 0) ? {} : { kid: record.kid }),
+            ...(record.at === (void 0) ? {} : { addedAt: record.at }),
+            ...(record.retiresAt === (void 0) ? {} : { retiresAt: record.retiresAt }),
+        });
+        this.keys.set(signer, existing);
+        this.emit("add", signer, record.at ?? Date.now(), record.kid);
+    }
+    /**
+     * Add a new key and retire the previous ones after the overlap window.
+     */
+    rotate(signer, publicKey, options) {
+        const overlapMs = Math.max(0, options.overlapMs ?? 0);
+        const existing = this.keys.get(signer) ?? [];
+        for (let index = 0; index < existing.length; index += 1) {
+            if (existing[index].retiresAt === (void 0)) {
+                existing[index].retiresAt = options.at + overlapMs;
+            }
+        }
+        existing.push({
+            key: publicKey,
+            ...(options.kid === (void 0) ? {} : { kid: options.kid }),
+            addedAt: options.at,
+        });
+        this.keys.set(signer, existing);
+        this.emit("rotate", signer, options.at, options.kid);
+    }
+    revoke(signer) {
+        this.revoked.add(signer);
+        this.emit("revoke", signer, Date.now());
+    }
+    revokeKid(signer, kid) {
+        this.revokedKids.add(`${signer}#${kid}`);
+        this.emit("revoke-kid", signer, Date.now(), kid);
+    }
+    prune(at) {
+        const entries = [...this.keys.entries()];
+        for (let index = 0; index < entries.length; index += 1) {
+            const signer = entries[index][0];
+            const records = entries[index][1];
+            this.keys.set(signer, records.filter((record) => record.retiresAt === (void 0) || record.retiresAt > at));
+        }
+        this.emit("prune", "", at);
+    }
+    candidates(signer, kid, at = Date.now()) {
+        if (this.revoked.has(signer)) {
+            return [];
+        }
+        const records = (this.keys.get(signer) ?? []).filter((record) => (record.retiresAt === (void 0) || record.retiresAt > at) && !this.revokedKids.has(`${signer}#${record.kid ?? ""}`));
+        if (kid !== (void 0)) {
+            const matching = records.filter((record) => record.kid === kid);
+            if (matching.length > 0) {
+                return matching.map((record) => record.key);
+            }
+        }
+        return records.map((record) => record.key);
+    }
+    get(signer, kid, at = Date.now()) {
+        return this.candidates(signer, kid, at)[0];
+    }
+}
+export const generateGovernanceSigners = async (signers, kidPrefix = "gov") => {
+    const result = [];
+    for (let index = 0; index < signers.length; index += 1) {
+        const signer = signers[index];
+        result.push({ signer, key: await generateSigningKey(`${kidPrefix}.${signer}`) });
+    }
+    return result;
+};
+const signingBytes = (input) => Encoder.encode(canonical({
+    signer: input.signer,
+    subject: input.subject,
+    subjectId: input.subjectId,
+    subjectVersion: input.subjectVersion ?? null,
+    digest: input.digest,
+}));
+export const signGovernanceDigest = async (input) => {
+    const signature = await crypto.subtle.sign("Ed25519", input.signer.key.privateKey, signingBytes({
+        signer: input.signer.signer,
+        subject: input.subject,
+        subjectId: input.subjectId,
+        ...(input.subjectVersion === (void 0) ? {} : { subjectVersion: input.subjectVersion }),
+        digest: input.digest,
+    }));
+    return {
+        signer: input.signer.signer,
+        kid: input.signer.key.kid,
+        alg: "ed25519",
+        sig: toBase64Url(signature),
+        digest: input.digest,
+    };
+};
+export const verifyGovernanceSignature = async (input) => {
+    if (input.signature.alg !== "ed25519") {
+        return { ok: false, reasons: [`unsupported algorithm ${input.signature.alg}`] };
+    }
+    if (input.signature.digest !== input.digest) {
+        return { ok: false, reasons: ["signature covers a different digest"] };
+    }
+    const candidates = input.keyring.candidates(input.signature.signer, input.signature.kid);
+    if (candidates.length === 0) {
+        return { ok: false, reasons: [`unknown or revoked signer ${input.signature.signer}`] };
+    }
+    for (let index = 0; index < candidates.length; index += 1) {
+        const valid = await crypto.subtle.verify("Ed25519", candidates[index], fromBase64Url(input.signature.sig), signingBytes({
+            signer: input.signature.signer,
+            subject: input.subject,
+            subjectId: input.subjectId,
+            ...(input.subjectVersion === (void 0) ? {} : { subjectVersion: input.subjectVersion }),
+            digest: input.digest,
+        }));
+        if (valid) {
+            return { ok: true, reasons: [] };
+        }
+    }
+    return { ok: false, reasons: ["signature does not verify"] };
+};
+export const signGovernanceObject = async (input) => {
+    if (input.signers.length === 0) {
+        throw new GovernanceError("manifest-unsigned", "at least one cryptographic signer is required");
+    }
+    const seen = new Set();
+    const signatures = [];
+    for (let index = 0; index < input.signers.length; index += 1) {
+        const signer = input.signers[index];
+        if (seen.has(signer.signer)) {
+            throw new GovernanceError("manifest-unsigned", `${signer.signer} signed twice`);
+        }
+        seen.add(signer.signer);
+        signatures.push(await signGovernanceDigest({
+            signer,
+            subject: input.subject,
+            subjectId: input.subjectId,
+            ...(input.subjectVersion === (void 0) ? {} : { subjectVersion: input.subjectVersion }),
+            digest: input.digest,
+        }));
+    }
+    return {
+        kind: "governance-signatures",
+        subject: input.subject,
+        subjectId: input.subjectId,
+        ...(input.subjectVersion === (void 0) ? {} : { subjectVersion: input.subjectVersion }),
+        subjectDigest: input.digest,
+        signatures,
+    };
+};
+export const verifyGovernanceBundle = async (input) => {
+    const reasons = [];
+    if (input.bundle.kind !== "governance-signatures") {
+        reasons.push("not a governance signature bundle");
+    }
+    if (input.bundle.subject !== input.expected.subject) {
+        reasons.push(`subject mismatch: ${input.bundle.subject}`);
+    }
+    if (input.bundle.subjectId !== input.expected.subjectId) {
+        reasons.push(`subject id mismatch: ${input.bundle.subjectId}`);
+    }
+    if (input.bundle.subjectVersion !== input.expected.subjectVersion) {
+        reasons.push("subject version mismatch");
+    }
+    if (input.bundle.subjectDigest !== input.expected.digest) {
+        reasons.push("bundle digest does not match the subject");
+    }
+    if (input.bundle.signatures.length === 0) {
+        reasons.push("bundle has no signatures");
+    }
+    const seen = new Set();
+    for (let index = 0; index < input.bundle.signatures.length; index += 1) {
+        const signature = input.bundle.signatures[index];
+        if (seen.has(signature.signer)) {
+            reasons.push(`${signature.signer} signed twice`);
+            continue;
+        }
+        seen.add(signature.signer);
+        const verified = await verifyGovernanceSignature({
+            signature,
+            subject: input.expected.subject,
+            subjectId: input.expected.subjectId,
+            ...(input.expected.subjectVersion === (void 0) ? {} : { subjectVersion: input.expected.subjectVersion }),
+            digest: input.expected.digest,
+            keyring: input.keyring,
+        });
+        reasons.push(...verified.reasons);
+    }
+    if (input.requiredSigners !== (void 0)) {
+        for (let index = 0; index < input.requiredSigners.length; index += 1) {
+            const required = input.requiredSigners[index];
+            if (!seen.has(required)) {
+                reasons.push(`missing required signer ${required}`);
+            }
+        }
+    }
+    return { ok: reasons.length === 0, reasons };
+};

package/lib/governance/store.d.ts

@@ -0,0 +1,33 @@
+import type { AppendSink } from "../storage/appendLog.js";
+import type { AttentionManifest } from "./attentionManifest.js";
+import type { BoardReceipt } from "./context.js";
+import type { SwitchCredential } from "./credential.js";
+export type StoredGovernanceKind = "manifest" | "credential" | "receipt";
+export interface GovernanceStoreSnapshot {
+    manifests: AttentionManifest[];
+    credentials: SwitchCredential[];
+    receipts: BoardReceipt[];
+    count: number;
+}
+export declare class GovernanceStore {
+    private readonly log;
+    private readonly manifests;
+    private readonly credentials;
+    private readonly receipts;
+    private constructor();
+    static open(sink: AppendSink): Promise<GovernanceStore>;
+    private replay;
+    private apply;
+    saveManifest(manifest: AttentionManifest): Promise<void>;
+    saveCredential(credential: SwitchCredential): Promise<void>;
+    saveReceipt(receipt: BoardReceipt): Promise<void>;
+    getManifest(id: string): AttentionManifest | undefined;
+    getCredential(id: string): SwitchCredential | undefined;
+    getReceipt(id: string): BoardReceipt | undefined;
+    snapshot(): GovernanceStoreSnapshot;
+    verify(): {
+        ok: boolean;
+        reasons: string[];
+    };
+    get count(): number;
+}

package/lib/governance/store.js

@@ -0,0 +1,89 @@
+/**
+ * Durable store for the governance objects themselves.
+ *
+ * The audit chain records that an act happened; this store keeps the object a
+ * later process needs to resume: the latest manifest per id, credentials and
+ * board receipts. It is an append-only JSONL event log, so replaying the file
+ * reconstructs the latest state without trusting the writer's memory.
+ */
+import { AppendLog } from "../storage/appendLog.js";
+import { GovernanceError } from "./types.js";
+const isRecord = (value) => typeof (value) === "object" && value !== null && !Array.isArray(value);
+const isStoredRecord = (value) => isRecord(value) && (value.type === "manifest" || value.type === "credential" || value.type === "receipt") && isRecord(value.value);
+export class GovernanceStore {
+    log;
+    manifests = new Map();
+    credentials = new Map();
+    receipts = new Map();
+    constructor(log) {
+        this.log = log;
+    }
+    static async open(sink) {
+        const log = await AppendLog.open(sink);
+        const store = new GovernanceStore(log);
+        store.replay();
+        return store;
+    }
+    replay() {
+        const entries = this.log.entries();
+        for (let index = 0; index < entries.length; index += 1) {
+            const payload = entries[index].payload;
+            if (!isStoredRecord(payload)) {
+                throw new GovernanceError("registry-invalid", `entry ${index} is not a governance record`);
+            }
+            this.apply(payload);
+        }
+    }
+    apply(record) {
+        if (record.type === "manifest") {
+            const value = record.value;
+            const existing = this.manifests.get(value.id);
+            if (existing === (void 0) || existing.version <= value.version) {
+                this.manifests.set(value.id, value);
+            }
+            return;
+        }
+        if (record.type === "credential") {
+            const value = record.value;
+            this.credentials.set(value.id, value);
+            return;
+        }
+        const value = record.value;
+        this.receipts.set(value.id, value);
+    }
+    async saveManifest(manifest) {
+        await this.log.append("event", { type: "manifest", value: manifest });
+        this.apply({ type: "manifest", value: manifest });
+    }
+    async saveCredential(credential) {
+        await this.log.append("event", { type: "credential", value: credential });
+        this.apply({ type: "credential", value: credential });
+    }
+    async saveReceipt(receipt) {
+        await this.log.append("event", { type: "receipt", value: receipt });
+        this.apply({ type: "receipt", value: receipt });
+    }
+    getManifest(id) {
+        return this.manifests.get(id);
+    }
+    getCredential(id) {
+        return this.credentials.get(id);
+    }
+    getReceipt(id) {
+        return this.receipts.get(id);
+    }
+    snapshot() {
+        return {
+            manifests: [...this.manifests.values()].map((manifest) => JSON.parse(JSON.stringify(manifest))),
+            credentials: [...this.credentials.values()].map((credential) => JSON.parse(JSON.stringify(credential))),
+            receipts: [...this.receipts.values()].map((receipt) => JSON.parse(JSON.stringify(receipt))),
+            count: this.log.count,
+        };
+    }
+    verify() {
+        return this.log.verify();
+    }
+    get count() {
+        return this.log.count;
+    }
+}

package/lib/governance/switching.d.ts

@@ -0,0 +1,183 @@
+/**
+ * Perspective and mode switching orchestration (spec section 12).
+ *
+ * The primitives already exist: credentials, manifests, context layers and the
+ * budget. This module sequences them into the flows the description names:
+ * peer switch, downgrade, mode switch and scenario switch. It also builds the
+ * escalation plan, including the independent strategic context that must not
+ * inherit the execution reasoning chain.
+ */
+import type { Budget, Ref, Timestamp } from "../types/common.js";
+import type { ApprovalGrant, BehaviorConstraints, Elasticity, EvidenceFloor, ModeWeights, PerspectiveId, ScenarioId, SignerInput } from "./types.js";
+import type { AttentionManifest } from "./attentionManifest.js";
+import type { BudgetBinding, RederivePatch } from "./attentionManifest.js";
+import type { CredentialVerdict, SwitchCredential } from "./credential.js";
+import type { ScenarioModePlan } from "./matrix.js";
+/**
+ * The three-party approval set for a switch. HR, legal and finance each own one
+ * subject; the general manager issues.
+ */
+export interface SwitchApprovals {
+    generalManager: ApprovalGrant;
+    legal: ApprovalGrant;
+    finance: ApprovalGrant;
+    humanResources: ApprovalGrant;
+}
+export interface PeerSwitchInput {
+    /**
+     * The perspective that asked for the switch.
+     */
+    requester: PerspectiveId;
+    to: PerspectiveId;
+    reason: string;
+    scenario: ScenarioId;
+    modes?: Partial<ModeWeights>;
+    targetManifest: AttentionManifest;
+    visibleScope: Ref[];
+    payloadRefs?: Ref[];
+    quota: Budget;
+    elasticity: Elasticity;
+    constraints: BehaviorConstraints;
+    issuedAt: Timestamp;
+    ttlMs?: number;
+    at: Timestamp;
+    approvals: SwitchApprovals;
+    signers: readonly SignerInput[];
+}
+export interface PeerSwitchResult {
+    credential: SwitchCredential;
+    verdict: CredentialVerdict;
+    target: AttentionManifest;
+    steps: string[];
+}
+/**
+ * Peer switch: HR confirms the target, legal clears the scope, finance freezes
+ * the quota, the general manager issues the credential, and the target loads
+ * its own manifest after the credential verifies.
+ */
+export declare const planPeerSwitch: (input: PeerSwitchInput) => PeerSwitchResult;
+export interface DowngradeInput {
+    requester: PerspectiveId;
+    /**
+     * The strategic perspective being left behind (board or supervisory).
+     */
+    from: PerspectiveId;
+    to: PerspectiveId;
+    reason: string;
+    targetManifest: AttentionManifest;
+    visibleScope: Ref[];
+    quota: Budget;
+    elasticity: Elasticity;
+    constraints: BehaviorConstraints;
+    issuedAt: Timestamp;
+    ttlMs?: number;
+    at: Timestamp;
+    approvals: {
+        generalManager: ApprovalGrant;
+        legal: ApprovalGrant;
+        finance: ApprovalGrant;
+        humanResources: ApprovalGrant;
+    };
+    signers: readonly SignerInput[];
+}
+/**
+ * Downgrade: the strategic layer returns authority to an execution
+ * perspective. Finance approves the budget recovery, legal approves the
+ * post-downgrade behaviour constraints, HR confirms the target is available.
+ */
+export declare const planDowngrade: (input: DowngradeInput) => PeerSwitchResult;
+export interface ModeSwitchInput {
+    manifest: AttentionManifest;
+    modes: Partial<ModeWeights>;
+    by: PerspectiveId;
+    at: Timestamp;
+    signoff: SignerInput;
+    approvals?: {
+        modeWeights?: ApprovalGrant;
+        finance?: ApprovalGrant;
+        legal?: ApprovalGrant;
+    };
+    evidenceFloor?: EvidenceFloor;
+    budget?: BudgetBinding;
+}
+export interface ModeSwitchResult {
+    manifest: AttentionManifest;
+    drift: number;
+    approvalRequired: boolean;
+    plan: ScenarioModePlan;
+    steps: string[];
+}
+/**
+ * Mode switch: update the manifest's weights, floor and elasticity without
+ * switching the perspective. Drift above 0.15 needs the general manager; an
+ * elasticity change needs finance; a floor change needs legal.
+ */
+export declare const switchMode: (input: ModeSwitchInput) => ModeSwitchResult;
+export interface ScenarioSwitchInput {
+    manifest: AttentionManifest;
+    scenario: ScenarioId;
+    modes?: Partial<ModeWeights>;
+    at: Timestamp;
+    signers: readonly SignerInput[];
+    approvals: {
+        scenario: ApprovalGrant;
+        board?: ApprovalGrant;
+        finance?: ApprovalGrant;
+        legal?: ApprovalGrant;
+    };
+    patch?: Omit<RederivePatch, "scenario" | "modes">;
+    /**
+     * Set when the new scenario is entered through the escalation path.
+     */
+    crossScenarioEscalation?: boolean;
+}
+export interface ScenarioSwitchResult {
+    manifest: AttentionManifest;
+    plan: ScenarioModePlan;
+    steps: string[];
+}
+/**
+ * Scenario switch: re-derive the manifest (version increments, parent digest
+ * recorded) instead of patching weights. A cross-scenario escalation also needs
+ * the board.
+ */
+export declare const switchScenario: (input: ScenarioSwitchInput) => ScenarioSwitchResult;
+export type EscalationKind = "audit" | "strategy" | "final" | "compliance";
+export interface EscalationInput {
+    from: PerspectiveId;
+    kind: EscalationKind;
+    reason: string;
+    evidence: Ref[];
+    at: Timestamp;
+    goal: string;
+    strategySummary: string;
+    approvals: {
+        initiate: ApprovalGrant;
+        reserve: ApprovalGrant;
+        readiness: ApprovalGrant;
+        authorization: ApprovalGrant;
+    };
+}
+export interface IndependentContext {
+    goal: string;
+    strategySummary: string;
+    evidence: Ref[];
+    request: string;
+    /**
+     * Always false: the strategic layer does not inherit the execution chain.
+     */
+    inheritsPrivateReasoning: false;
+}
+export interface EscalationPlan {
+    target: PerspectiveId;
+    independent: IndependentContext;
+    approvals: ApprovalGrant[];
+    authorization: string;
+    steps: string[];
+}
+/**
+ * Escalation plan: the finance reserve and HR readiness gates are the same for
+ * every type; the type decides who signs the authorisation. The strategic layer
+ * receives global core, evidence refs and the request summary only.
+ */
+export declare const planEscalation: (input: EscalationInput) => EscalationPlan;