@ashlr/hub 3.2.6 → 3.3.0

package/dist/core/daemon/activation-permit.d.ts

@@ -1,15 +1,84 @@
 import { type KeyObject } from 'node:crypto';
 import { type BuildIdentity } from '../build-identity.js';
 import type { AshlrConfig } from '../types.js';
+/**
+ * M461 → M470 daemon activation authority.
+ *
+ * The default for anyone who has not explicitly run `ashlr activation init`
+ * is EXACTLY today's behavior: every guard denies, with the same reasons as
+ * before. Authority only exists once an operator:
+ *
+ *   1. Runs `ashlr activation init` — generates an Ed25519 keypair on this
+ *      machine (private key never leaves it) and registers the public half
+ *      as a trust root in ~/.ashlr/activation/trust-roots.json (0600, dir
+ *      0700, owned by the operator's uid — checked on every read).
+ *   2. Runs `ashlr activation grant <scope...>` — signs and mints either a
+ *      single-use activation PERMIT (scopes: once, resident) consumed by
+ *      `daemon start`, or a standing, expiring GRANT (scopes: residentStanding,
+ *      conductor, install, automerge, repair, deploy) checked on every call to
+ *      the corresponding guard.
+ *
+ * `resident` is grantable BOTH ways, and both forms remain live:
+ *   - one-shot `resident` permit: fixed 2-minute window, requires a human to
+ *     run `grant` immediately before `daemon start`. Unusable after a reboot
+ *     with nobody present.
+ *   - standing `residentStanding` grant: up to the normal 30-day cap, checked
+ *     at resident-daemon startup instead of requiring a fresh permit — this is
+ *     what lets a launchd/systemd/Task-Scheduler-triggered restart authorize
+ *     itself with no human in the loop. `daemon start` (resident mode) tries
+ *     the standing grant first and falls back to the one-shot permit path
+ *     unchanged, so an operator who never grants `residentStanding` sees
+ *     EXACTLY today's one-shot-only behavior.
+ *
+ * Both permits and grants are Ed25519-signed, scoped, expiring, and
+ * independently revocable (`ashlr activation revoke`). Every init / grant /
+ * revoke / consume / denial writes an audit row via ../sandbox/audit.js so
+ * an operator can answer "who activated this fleet, when, with what scope."
+ *
+ * Revocation of a standing grant is file-based: it stops the NEXT
+ * authorization check, immediately. For `residentStanding` specifically it is
+ * stronger than that — because standing grants are not single-use (unlike the
+ * one-shot capability, which a resident loop must consume exactly once, see
+ * `tick()`'s `activationScope` handling in ../loop.ts), a resident daemon that
+ * started off a standing grant re-checks it on every tick and stops at the
+ * next one if the grant is revoked, expired, or its trust root is revoked —
+ * not just at the next `daemon start`. It cannot interrupt a tick already in
+ * flight.
+ *
+ * File loading fails CLOSED on every ambiguity: missing, unreadable, wrong
+ * permissions, wrong owner, symlinked, malformed, or non-canonically
+ * encoded trust-root/grant/permit files are all treated as "no authority" —
+ * never as "trust everything." Windows is denied outright: node:fs chmod()
+ * on Windows does not restrict per-user read access on NTFS (it only
+ * toggles the read-only attribute), so the "reject world/group-readable
+ * private files" invariant this module depends on cannot be enforced there.
+ */
 declare const POLICY_VERSION = "m461-proposal-once-v1";
+/** Hard cap on any standing grant's validity window (30 days). */
+export declare const MAX_STANDING_GRANT_VALIDITY_MS: number;
+/** Default TTL `ashlr activation grant` uses when --ttl is not given (24h). */
+export declare const DEFAULT_STANDING_GRANT_VALIDITY_MS: number;
 declare const capabilityBrand: unique symbol;
+/** Every independently grantable scope key, in canonical order. Used by the CLI to validate `grant`/status output. */
+export declare const DAEMON_ACTIVATION_SCOPE_KEYS: readonly ["once", "resident", "residentStanding", "conductor", "automerge", "repair", "deploy", "install", "proposalOnly"];
+declare const SCOPE_KEYS: readonly ["once", "resident", "residentStanding", "conductor", "automerge", "repair", "deploy", "install", "proposalOnly"];
+export type DaemonActivationScopeKey = typeof SCOPE_KEYS[number];
+/** A real, independently grantable capability set. Unknown fields are rejected. */
+export type DaemonActivationGrantScope = {
+    [K in DaemonActivationScopeKey]: boolean;
+};
+/** All-false scope — the base every CLI `grant` invocation flips bits on top of. */
+export declare const EMPTY_DAEMON_ACTIVATION_SCOPE: DaemonActivationGrantScope;
 /**
  * Runtime authority is nominal and process-local. Objects that merely match
- * this public shape are rejected by isDaemonActivationCapability().
+ * this public shape are rejected by isDaemonActivationCapability(). `scope`
+ * is readable without consuming the capability — only isDaemonActivationCapability()
+ * consumes the single-use claim.
  */
 export interface DaemonActivationCapability {
     readonly kind: 'proposal-once';
     readonly permitId: string;
+    readonly scope: DaemonActivationGrantScope;
     readonly [capabilityBrand]: true;
 }
 export interface DaemonActivationOptions {
@@ -27,6 +96,16 @@ export interface DaemonActivationPermitResult {
     receiptPath?: string;
     capability?: DaemonActivationCapability;
     configSnapshot?: AshlrConfig;
+    /**
+     * Present only when authorized via a standing `residentStanding` grant
+     * rather than a one-shot permit. Standing grants are not single-use, so
+     * this scope is handed to the caller directly — there is no WeakMap
+     * capability to consume, and none of `isDaemonActivationCapability`'s
+     * one-shot semantics apply to it.
+     */
+    scope?: DaemonActivationGrantScope;
+    /** Present only when `scope` is, so callers can re-check liveness per use. */
+    grantId?: string;
 }
 export interface DaemonActivationReadiness {
     schemaVersion: 1;
@@ -35,17 +114,38 @@ export interface DaemonActivationReadiness {
     sourceState: 'healthy' | 'degraded';
     state: 'ready' | 'blocked' | 'degraded';
     commandEligible: boolean;
-    requestedShape: 'proposal-once';
+    requestedShape: 'proposal-once' | 'resident';
     trustRootCount: number;
-    residentAuthorized: false;
-    installAuthorized: false;
-    repairAuthorized: false;
+    residentAuthorized: boolean;
+    /** Whether a currently valid standing `residentStanding` grant exists, independent of any pending one-shot permit. */
+    residentStandingAuthorized: boolean;
+    installAuthorized: boolean;
+    repairAuthorized: boolean;
     reason: string;
 }
 export interface DaemonActivationTrustRoot {
     keyId: string;
     publicKeyPem: string;
 }
+/** Full operator-owned trust-root record, incl. mutable local revocation state. */
+export interface DaemonActivationTrustRootRecord extends DaemonActivationTrustRoot {
+    createdAt: string;
+    /** Mutable, operator-set, NOT part of any signature. Non-null = revoked, immediately. */
+    revokedAt: string | null;
+    label: string;
+}
+/** A signed, expiring, independently revocable standing capability grant. */
+export interface DaemonActivationGrantRecord {
+    schemaVersion: 1;
+    grantId: string;
+    keyId: string;
+    issuedAt: string;
+    expiresAt: string;
+    scope: DaemonActivationGrantScope;
+    signature: string;
+    /** Mutable, operator-set, NOT part of the signature. Non-null = revoked, immediately. */
+    revokedAt: string | null;
+}
 export interface DaemonActivationFileBinding {
     path: string;
     sha256: string;
@@ -69,20 +169,7 @@ export interface DaemonActivationPermitPayload {
     keyId: string;
     issuedAt: string;
     expiresAt: string;
-    scope: {
-        action: 'daemon-proposal-once';
-        once: true;
-        dryRun: false;
-        resident: false;
-        drain: false;
-        drainLimit: null;
-        proposalOnly: true;
-        automerge: false;
-        repair: false;
-        deploy: false;
-        install: false;
-        selfTarget: false;
-    };
+    scope: DaemonActivationGrantScope;
     bindings: {
         configDigest: string;
         buildIdentity: BuildIdentity;
@@ -103,6 +190,14 @@ export interface DaemonActivationPermitVerification {
     reason: string;
     permitId?: string;
     payloadDigest?: string;
+    /**
+     * Populated only when reason === 'permit-runtime-binding-mismatch': the
+     * top-level binding field names (of DaemonActivationPermitPayload.bindings)
+     * whose signed value differs from the current runtime value. A fail-closed
+     * gate that can't say WHICH binding differed is very hard to operate — this
+     * turns the single opaque reason code into an actionable diagnostic.
+     */
+    mismatchedBindings?: readonly string[];
 }
 export interface DaemonActivationPermitTestConsumerOptions {
     trustRoots: readonly DaemonActivationTrustRoot[];
@@ -114,20 +209,8 @@ export interface DaemonActivationPermitTestInspectionOptions {
     context: DaemonActivationRuntimeContext;
     platform?: NodeJS.Platform;
 }
-/**
- * Provisioning a production trust root requires a reviewed source change.
- * No environment variable, config field, CLI argument, or writable trust file
- * can add authority at runtime.
- */
-export declare const DAEMON_ACTIVATION_TRUST_ROOTS: readonly Readonly<DaemonActivationTrustRoot>[];
 /** Validate and consume a capability exactly once. */
 export declare function isDaemonActivationCapability(value: unknown): value is DaemonActivationCapability;
-/**
- * Goal and simple conductors have broader authority than M461's one-item
- * proposal profile. They remain dormant until a separately reviewed permit
- * contract exists for those entry points.
- */
-export declare function liveConductorActivationAuthorized(): boolean;
 export declare function canonicalizeDaemonActivationValue(value: unknown): string;
 export declare function daemonActivationConfigDigest(cfg: AshlrConfig): string;
 export declare function verifyDaemonActivationPermit(value: unknown, context: DaemonActivationRuntimeContext, trustRoots: readonly DaemonActivationTrustRoot[]): DaemonActivationPermitVerification;
@@ -137,16 +220,168 @@ export declare function buildDaemonActivationPermitPayload(input: {
     keyId: string;
     issuedAt: string;
     expiresAt: string;
+    /** Defaults to the legacy {once, proposalOnly} grant when omitted. */
+    scope?: DaemonActivationGrantScope;
     context: DaemonActivationRuntimeContext;
 }): DaemonActivationPermitPayload;
 export declare function signDaemonActivationPermit(payload: DaemonActivationPermitPayload, privateKey: string | KeyObject): DaemonActivationPermitEnvelope;
 /** Read-only helper for release packaging and substitution verification. */
 export declare function daemonActivationReleaseTreeBinding(entrypointPath: string): DaemonActivationFileBinding;
+/**
+ * Fingerprints "this authority store instance" — the ~/.ashlr directory a
+ * permit is bound to — so a permit can't be replayed against a different
+ * store (e.g. copied to another machine, or after a full delete+recreate).
+ *
+ * Deliberately uses dev+ino, NOT mtime. ~/.ashlr's own mtime changes every
+ * time a direct child is created or removed — and ordinary `daemon start`
+ * does exactly that before it ever reaches this check: acquireDaemonLock()
+ * (src/core/daemon/state.ts) creates ~/.ashlr/daemon.lock via
+ * `writeFileSync(..., {flag:'wx'})`, a brand-new direct child of ~/.ashlr.
+ * Binding to mtime meant every freshly minted permit was invalidated by the
+ * daemon's own startup lock-file creation, 100% reproducibly, before it
+ * could ever be consumed — a self-inflicted permit-runtime-binding-mismatch,
+ * not a real "different store" signal. dev+ino uniquely and STABLY identify
+ * the directory's inode: they survive ordinary child churn (locks, control
+ * files, receipts) and change only if ~/.ashlr is deleted and recreated (or
+ * moved to a different filesystem) — exactly the case this binding exists
+ * to catch.
+ */
+export declare function daemonActivationAuthorityStateDigest(): string;
 export declare function daemonActivationPermitPath(): string;
 export declare function daemonActivationReceiptPath(permitId: string): string;
+export declare function daemonActivationDirPath(): string;
+export declare function daemonActivationTrustRootsPath(): string;
+export declare function daemonActivationGrantsPath(): string;
+export declare function daemonActivationOperatorKeyPath(): string;
+/**
+ * The ONLY source of production trust roots: an operator-owned, protected
+ * file the operator populates via `ashlr activation init`. Missing, unsafe,
+ * or malformed → []  — identical denial to before this file loading existed.
+ */
+export declare function loadDaemonActivationTrustRoots(): readonly DaemonActivationTrustRoot[];
+/** Full trust-root status (incl. revoked history) for `ashlr activation status`. */
+export declare function daemonActivationTrustRootStatus(): {
+    ok: true;
+    records: readonly DaemonActivationTrustRootRecord[];
+} | {
+    ok: false;
+    reason: string;
+};
+/** Full standing-grant status (incl. revoked/expired history) for `ashlr activation status`. */
+export declare function daemonActivationGrantStatus(): {
+    ok: true;
+    records: readonly DaemonActivationGrantRecord[];
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function signDaemonActivationGrant(input: {
+    grantId: string;
+    keyId: string;
+    issuedAt: string;
+    expiresAt: string;
+    scope: DaemonActivationGrantScope;
+    privateKey: string | KeyObject;
+}): DaemonActivationGrantRecord;
+export declare function daemonActivationScopeGranted(scopeKey: DaemonActivationScopeKey): {
+    granted: boolean;
+    reason: string;
+};
+/**
+ * The goal and simple conductors consult this every cycle. Real, gated,
+ * revocable authority: granted only after `ashlr activation init` +
+ * `ashlr activation grant conductor`. Default (no grant) is denied, exactly
+ * as before this mechanism existed. Every check is audited.
+ */
+export declare function liveConductorActivationAuthorized(): boolean;
+export declare function generateDaemonActivationOperatorKeypair(): {
+    privateKeyPem: string;
+    publicKeyPem: string;
+};
+/**
+ * Generates an Ed25519 keypair on THIS machine (private key never leaves it,
+ * written 0600 under an 0700 directory) and registers the public half as a
+ * new active trust root. Refuses to silently clobber an existing active
+ * root or key file unless `force` is set (key rotation: the new root is
+ * ADDED, not swapped in place, so grants signed by an older still-active
+ * root keep working until explicitly revoked).
+ */
+export declare function daemonActivationInit(input: {
+    label?: string;
+    force?: boolean;
+}): {
+    ok: true;
+    keyId: string;
+    publicKeyPem: string;
+    rotated: boolean;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function daemonActivationRevokeTrustRoot(keyId: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function daemonActivationRevokeGrant(grantId: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Mints a signed, expiring standing grant (conductor/automerge/repair/deploy/install/proposalOnly). */
+export declare function daemonActivationMintStandingGrant(input: {
+    scope: DaemonActivationGrantScope;
+    ttlMs: number;
+}): {
+    ok: true;
+    record: DaemonActivationGrantRecord;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Mints and pins a single-use activation permit (once/resident scopes) to
+ * daemonActivationPermitPath(), ready for `ashlr daemon start` to consume.
+ * Signs against THIS exact machine's current build (executable/entrypoint/
+ * release-tree hashes) — an operator runs this locally, immediately before
+ * starting the daemon it authorizes.
+ */
+export declare function daemonActivationMintOneShotPermit(input: {
+    cfg: AshlrConfig;
+    scope: DaemonActivationGrantScope;
+}): {
+    ok: true;
+    permitId: string;
+    permitPath: string;
+    expiresAt: string;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface DaemonActivationPendingPermitBindingDiagnosis {
+    ok: boolean;
+    reason: string;
+    /** Field name -> {signed at mint time, computed right now}. Only present for mismatched fields. */
+    mismatches?: Record<string, {
+        signed: unknown;
+        current: unknown;
+    }>;
+}
+/**
+ * Read-only diagnostic (never authorizes, never consumes) for `ashlr
+ * activation status`: peeks the pending one-shot permit, recomputes the
+ * current runtime context, and reports exactly which binding field(s)
+ * differ and what the two values were. `permit-runtime-binding-mismatch`
+ * alone can't tell an operator what to fix — this can.
+ */
+export declare function daemonActivationDiagnosePendingPermitBindings(cfg: AshlrConfig): DaemonActivationPendingPermitBindingDiagnosis;
 /**
- * Runtime entrypoint. Its immutable repository-owned roots are the only path
- * that can mint an in-process activation capability.
+ * Runtime entrypoint. Trust roots come ONLY from the operator-owned store
+ * (see loadDaemonActivationTrustRoots); an npm consumer who never runs
+ * `ashlr activation init` sees the store as empty and gets today's exact
+ * denial. Every consume attempt — authorized or refused — is audited.
  */
 export declare function consumeDaemonActivationPermit(cfg: AshlrConfig, opts: DaemonActivationOptions): DaemonActivationPermitResult;
 /**
@@ -161,4 +396,93 @@ export declare function inspectDaemonActivationPermitForVerification(cfg: AshlrC
  * durability with injected roots, but deliberately cannot mint authority.
  */
 export declare function consumeDaemonActivationPermitForVerification(cfg: AshlrConfig, opts: DaemonActivationOptions, options: DaemonActivationPermitTestConsumerOptions): DaemonActivationPermitResult;
+declare const GOAL_CONDUCTOR_POLICY_VERSION = "goal-conductor-proposal-once-v1";
+export declare const GOAL_CONDUCTOR_ONCE_MAX_TOKENS = 50000;
+export declare const GOAL_CONDUCTOR_ONCE_MAX_STEPS = 12;
+declare const goalConductorCapabilityBrand: unique symbol;
+export interface GoalConductorActivationTarget {
+    goalId: string;
+    milestoneId: string;
+    goalDigest: string;
+    projectPath: string;
+}
+export interface GoalConductorActivationContext extends DaemonActivationRuntimeContext {
+    target: GoalConductorActivationTarget;
+}
+export interface GoalConductorActivationPermitPayload {
+    schemaVersion: 1;
+    policyVersion: typeof GOAL_CONDUCTOR_POLICY_VERSION;
+    permitId: string;
+    nonce: string;
+    keyId: string;
+    issuedAt: string;
+    expiresAt: string;
+    scope: {
+        action: 'goal-conductor-proposal-once';
+        once: true;
+        dryRun: false;
+        resident: false;
+        maxGoals: 1;
+        maxMilestones: 1;
+        maxRetries: 0;
+        allowCloud: false;
+        allowAnyRepo: false;
+        daemonFallback: false;
+        proposalOnly: true;
+        automerge: false;
+        repair: false;
+        deploy: false;
+        install: false;
+        selfTarget: false;
+        maxTokens: typeof GOAL_CONDUCTOR_ONCE_MAX_TOKENS;
+        maxSteps: typeof GOAL_CONDUCTOR_ONCE_MAX_STEPS;
+    };
+    bindings: DaemonActivationPermitPayload['bindings'] & {
+        target: GoalConductorActivationTarget;
+    };
+}
+export interface GoalConductorActivationPermitEnvelope {
+    payload: GoalConductorActivationPermitPayload;
+    signature: string;
+}
+export interface GoalConductorActivationCapability {
+    readonly kind: 'goal-conductor-proposal-once';
+    readonly permitId: string;
+    readonly target: Readonly<GoalConductorActivationTarget>;
+    readonly [goalConductorCapabilityBrand]: true;
+}
+export interface GoalConductorActivationPermitResult {
+    authorized: boolean;
+    reason: string;
+    permitId?: string;
+    receiptPath?: string;
+    capability?: GoalConductorActivationCapability;
+    configSnapshot?: AshlrConfig;
+}
+export interface GoalConductorActivationTestConsumerOptions {
+    trustRoots: readonly DaemonActivationTrustRoot[];
+    context?: GoalConductorActivationContext;
+    afterReceiptPersisted?: () => void;
+}
+/** Immutable repository-owned roots. Intentionally empty in production. */
+export declare const GOAL_CONDUCTOR_ACTIVATION_TRUST_ROOTS: readonly Readonly<DaemonActivationTrustRoot>[];
+export declare function parseGoalConductorActivationPermitEnvelope(value: unknown): GoalConductorActivationPermitEnvelope | null;
+export declare function buildGoalConductorActivationPermitPayload(input: {
+    permitId: string;
+    nonce: string;
+    keyId: string;
+    issuedAt: string;
+    expiresAt: string;
+    context: GoalConductorActivationContext;
+}): GoalConductorActivationPermitPayload;
+export declare function signGoalConductorActivationPermit(payload: GoalConductorActivationPermitPayload, privateKey: string | KeyObject): GoalConductorActivationPermitEnvelope;
+export declare function verifyGoalConductorActivationPermit(value: unknown, context: GoalConductorActivationContext, roots: readonly DaemonActivationTrustRoot[]): DaemonActivationPermitVerification;
+export declare function goalConductorActivationPermitPath(): string;
+export declare function goalConductorActivationReceiptPath(permitId: string): string;
+export declare function goalConductorActivationNonceReceiptPath(nonceDigest: string): string;
+/** Collect the same read-only runtime binding used at permit consumption. */
+export declare function collectGoalConductorActivationContext(cfg: AshlrConfig, target: GoalConductorActivationTarget): GoalConductorActivationContext;
+export declare function isGoalConductorActivationCapability(value: unknown, target: GoalConductorActivationTarget): value is GoalConductorActivationCapability;
+export declare function consumeGoalConductorActivationPermit(cfg: AshlrConfig, target: GoalConductorActivationTarget): GoalConductorActivationPermitResult;
+export declare function consumeGoalConductorActivationPermitForVerification(cfg: AshlrConfig, target: GoalConductorActivationTarget, options: GoalConductorActivationTestConsumerOptions): GoalConductorActivationPermitResult;
 export {};