@skrr-ai/auth-core 0.1.3 → 0.1.5

package/dist/esm/releaseManifest.d.ts

@@ -0,0 +1,161 @@
+import { type ReleaseKey } from './releaseKeys.js';
+export type { ReleaseKey } from './releaseKeys.js';
+/**
+ * One entry in a v2 multi-signature envelope. `sig` is a base64 ed25519
+ * signature over the EXACT SAME bytes as the v1 scalar `sig` (buildArtifact/
+ * ManifestMessage) — v2 is an envelope change, not a wire-format change. The
+ * `keyId` is an ADVISORY label only: verification trial-verifies every sig
+ * against every pinned key and NEVER consults keyId, so a mislabeled keyId can
+ * neither grant nor withhold trust (this structurally defeats keyId
+ * substitution). It exists for operator diagnostics ("which key signed this?").
+ */
+export interface ManifestSignature {
+    keyId: string;
+    /** base64 ed25519 signature over the same bytes as the v1 `sig`. */
+    sig: string;
+}
+/**
+ * v-delta (optional): a differential-update patch that transforms a specific
+ * PRIOR version's binary into this release's binary — a brotli-compressed
+ * fossil delta. UNSIGNED, exactly like `keyId`/`size`/`sigs` (NOT part of
+ * buildArtifactMessage/buildManifestMessage), so it never changes the signed
+ * bytes and #782's envelope invariant holds. Trust comes SOLELY from verifying
+ * the RECONSTRUCTED binary against the signed `sha256` + ed25519 gates: a
+ * tampered/garbage delta yields a non-matching binary and the daemon falls back
+ * to the full signed download. `sha256` here is TRANSPORT integrity of the patch
+ * file only — NEVER an install gate.
+ */
+export interface DeltaDescriptor {
+    /** Absolute public URL of the brotli-compressed fossil delta patch. */
+    url: string;
+    /** Lowercase hex sha256 of the patch file — transport integrity, not trust. */
+    sha256: string;
+    /** Size of the patch file in bytes. */
+    size: number;
+}
+/** One downloadable, immutable binary for a single `<platform>-<arch>` target. */
+export interface PlatformArtifact {
+    /** Bare filename, e.g. `oversky-darwin-arm64`. */
+    file: string;
+    /** Absolute public URL under the CloudFront feed. */
+    url: string;
+    /** Lowercase hex sha256 of the binary bytes. */
+    sha256: string;
+    /** Size in bytes. */
+    size: number;
+    /** base64 ed25519 signature over buildArtifactMessage(...) — the PRIMARY key. */
+    sig: string;
+    /**
+     * v2 (optional): EVERY signature (primary + rotation key) over the same
+     * bytes as `sig`. Emitted ONLY during a key-rotation window (>1 signing key);
+     * absent in steady single-key state, so a normal manifest is byte-identical
+     * to v1. When present it is the authoritative set — see verifyWithKeysMulti.
+     */
+    sigs?: ManifestSignature[];
+    /**
+     * v-delta (optional, UNSIGNED): differential-update patches keyed by the
+     * from-version they apply to (e.g. `"0.8.0"`). Absent in steady state. See
+     * DeltaDescriptor — the reconstructed binary is verified against `sha256`
+     * above, so deltas add NO trust surface.
+     */
+    deltas?: Record<string, DeltaDescriptor>;
+}
+/**
+ * The signed release manifest. `platforms` is keyed by `<platform>-<arch>`
+ * (e.g. `darwin-arm64`, `linux-x64`). The top-level `sig` covers
+ * buildManifestMessage(manifest-without-sig).
+ */
+export interface DaemonVersionManifest<TPolicy = unknown> {
+    schemaVersion: number;
+    version: string;
+    minimum: string;
+    forceUpdate: boolean;
+    keyId: string;
+    platforms: Record<string, PlatformArtifact>;
+    /**
+     * base64 ed25519 signature over buildManifestMessage(this-without-sig) — the
+     * PRIMARY key. Kept populated even in v2 so an OLD (v1-only) daemon still
+     * verifies against the key the lagging fleet trusts.
+     */
+    sig: string;
+    /**
+     * v2 (optional): EVERY manifest signature (primary + rotation key). Emitted
+     * ONLY during a rotation window; when present it is authoritative — see
+     * verifyWithKeysMulti. `schemaVersion` stays a reader hint (unsigned, inert);
+     * v2 is detected by `Array.isArray(sigs)`, not by the version number.
+     */
+    sigs?: ManifestSignature[];
+    /**
+     * Independently signed release decision envelope. It is intentionally not
+     * part of the v1 manifest message so existing daemons can ignore it; newer
+     * daemons verify this nested signature before honouring compatibility or
+     * rollout controls.
+     */
+    policy?: TPolicy;
+}
+/**
+ * Canonical bytes signed for a single platform artifact. Newline-joined, fixed
+ * field order, `v1` tag. `sha256` is lowercased so the message is stable
+ * regardless of the hex casing the caller supplies.
+ */
+export declare function buildArtifactMessage(a: {
+    platform: string;
+    version: string;
+    sha256: string;
+    url: string;
+}): string;
+/**
+ * Canonical bytes signed for the whole manifest (excluding the top-level
+ * `sig`). Platform keys are sorted so the message is independent of JSON key
+ * order; each contributes `<platform>=<sha256-lower>`. `forceUpdate` is
+ * serialized strictly (`String(forceUpdate === true)` → `"true"`/`"false"`).
+ */
+export declare function buildManifestMessage(m: {
+    version: string;
+    minimum: string;
+    forceUpdate: boolean;
+    platforms: Record<string, {
+        sha256: string;
+    }>;
+}): string;
+/**
+ * Discriminated verification result:
+ *  - `{ ok: true }`         — signature verified against a pinned key.
+ *  - `{ ok: false, reason }` — keys are present but nothing verified (FAIL-CLOSED).
+ *  - `{ disabled: true }`   — no keys pinned; verification is intentionally off.
+ */
+export type VerifyResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+} | {
+    disabled: true;
+};
+/**
+ * Upper bound on signatures we will trial-verify per artifact/manifest. A
+ * rotation window needs at most 2–3 (current + next). `sigs[]` is NOT part of
+ * the signed bytes, so an attacker can pad it; this cap bounds the verify work
+ * they can force to O(MAX_SIGS × pinnedKeys) — a few hundred microseconds even
+ * at the cap. A valid signature placed beyond the cap is treated as absent.
+ */
+export declare const MAX_SIGS = 8;
+/**
+ * Verify a single platform artifact's `sig` over buildArtifactMessage(...).
+ * `platform` is the `<platform>-<arch>` key; `version` is the manifest version
+ * the artifact belongs to. Defaults to the baked-in pinned keys.
+ */
+export declare function verifyArtifact(platform: string, version: string, artifact: PlatformArtifact, keys?: readonly ReleaseKey[]): VerifyResult;
+/**
+ * Verify the manifest's top-level `sig` over buildManifestMessage(this).
+ * Defaults to the baked-in pinned keys.
+ */
+export declare function verifyManifest(manifest: DaemonVersionManifest, keys?: readonly ReleaseKey[]): VerifyResult;
+/**
+ * Look up a delta patch that transforms `fromVersion`'s binary into this
+ * artifact's binary. Returns null when none is advertised or the descriptor is
+ * malformed — the caller then does a full download. PURE; validates shape only
+ * (the delta is UNSIGNED, so trust comes from verifying the RECONSTRUCTED binary
+ * against the signed `artifact.sha256`, not from this metadata).
+ */
+export declare function getDeltaFor(artifact: PlatformArtifact, fromVersion: string): DeltaDescriptor | null;

package/dist/esm/releaseManifest.js

@@ -0,0 +1,227 @@
+/**
+ * release-manifest.ts — signed daemon release manifest: types, canonical
+ * signature messages, and offline ed25519 verification.
+ *
+ * PURE: depends only on `node:crypto` (plus the sibling `release-keys.ts` for
+ * the pinned trust anchors). No Electron, no logger, no fs — so it is
+ * unit-testable in isolation and safe to import from the CI release signer.
+ *
+ * SINGLE SOURCE OF TRUTH: `buildArtifactMessage` and `buildManifestMessage`
+ * define the exact bytes that get signed. The CI signer MUST import these
+ * functions rather than reimplement them — that is what eliminates
+ * signer/verifier drift. Any change here is a wire-format change and must bump
+ * the embedded `v1` tag.
+ *
+ * Mechanics mirror `desktop/src/main/updater/policySignature.ts`: the public
+ * key is base64 DER-SPKI, verified with `crypto.verify(null, ...)` (ed25519
+ * takes no digest algorithm).
+ *
+ * WHY IT LIVES IN auth-core NOW
+ *
+ * It lived in `daemon/src/release-manifest.ts`, and `skyCodeChannels.ts` beside
+ * it recorded the reason for stopping there: "the installer, the signature
+ * verification and the promotion machinery stay in the daemon, which is the
+ * only process that performs them." That premise held exactly until the CLI
+ * had to install the daemon — `skrr daemon install` on a machine with no
+ * `skrrd` cannot ask the daemon to verify the daemon.
+ *
+ * So this is the same road that move was on, not a reversal of it. A MIRROR in
+ * the CLI is the alternative and is the wrong one, with precedent: OSK-3894
+ * shipped a mirrored harness-trust table and OSK-3897 removed it, because a
+ * mirror proves two copies agree rather than proving there is one copy. For a
+ * TRUST ROOT that argument is not stylistic — a second copy of the pinned keys
+ * is a second thing that can be edited, and the edit that matters (emptying the
+ * array) disables verification silently.
+ *
+ * `SignedReleasePolicy` did NOT move. It is the daemon's own decision envelope,
+ * so the manifest is generic over it and the daemon narrows it back.
+ */
+import { createPublicKey, verify as verifyEd25519 } from 'node:crypto';
+import { OVERSKY_RELEASE_PUBLIC_KEYS } from './releaseKeys.js';
+// ---------------------------------------------------------------------------
+// Canonical signature messages — THE contract. Do not reformat casually.
+// ---------------------------------------------------------------------------
+/**
+ * Canonical bytes signed for a single platform artifact. Newline-joined, fixed
+ * field order, `v1` tag. `sha256` is lowercased so the message is stable
+ * regardless of the hex casing the caller supplies.
+ */
+export function buildArtifactMessage(a) {
+    return [
+        'oversky-daemon-artifact',
+        'v1',
+        a.platform,
+        a.version,
+        a.sha256.toLowerCase(),
+        a.url,
+    ].join('\n');
+}
+/**
+ * Canonical bytes signed for the whole manifest (excluding the top-level
+ * `sig`). Platform keys are sorted so the message is independent of JSON key
+ * order; each contributes `<platform>=<sha256-lower>`. `forceUpdate` is
+ * serialized strictly (`String(forceUpdate === true)` → `"true"`/`"false"`).
+ */
+export function buildManifestMessage(m) {
+    return [
+        'oversky-daemon-manifest',
+        'v1',
+        m.version,
+        m.minimum,
+        String(m.forceUpdate === true),
+        ...Object.keys(m.platforms)
+            .sort()
+            .map((p) => p + '=' + m.platforms[p].sha256.toLowerCase()),
+    ].join('\n');
+}
+/**
+ * Try `sigB64` against every pinned key (supports key rotation: current +
+ * next). Never throws — a malformed key or signature is just a failed attempt.
+ * Empty key set ⇒ `{ disabled: true }` so the caller can warn-and-proceed
+ * (mirrors desktop `MANIFEST_PUBLIC_KEY=''`).
+ */
+function verifyWithKeys(message, sigB64, keys) {
+    if (keys.length === 0)
+        return { disabled: true };
+    if (!sigB64)
+        return { ok: false, reason: 'missing signature' };
+    const msg = Buffer.from(message, 'utf8');
+    const sig = Buffer.from(sigB64, 'base64');
+    for (const k of keys) {
+        try {
+            const key = createPublicKey({
+                key: Buffer.from(k.publicKeySpkiB64, 'base64'),
+                format: 'der',
+                type: 'spki',
+            });
+            if (verifyEd25519(null, msg, key, sig)) {
+                return { ok: true };
+            }
+        }
+        catch {
+            // Malformed key material or verify error → try the next pinned key.
+        }
+    }
+    return { ok: false, reason: 'signature did not verify against any pinned key' };
+}
+/**
+ * Upper bound on signatures we will trial-verify per artifact/manifest. A
+ * rotation window needs at most 2–3 (current + next). `sigs[]` is NOT part of
+ * the signed bytes, so an attacker can pad it; this cap bounds the verify work
+ * they can force to O(MAX_SIGS × pinnedKeys) — a few hundred microseconds even
+ * at the cap. A valid signature placed beyond the cap is treated as absent.
+ */
+export const MAX_SIGS = 8;
+/**
+ * v2 acceptance: `{ ok: true }` if ANY provided signature verifies against ANY
+ * pinned key. This composes the two rotation axes — verifyWithKeys already
+ * loops every pinned KEY (key rotation); this adds the every-SIGNATURE loop —
+ * so a release dual-signed by [old, new] verifies for a daemon pinning only
+ * [old], only [new], or both. That is what makes rotation zero-downtime.
+ *
+ * Posture is identical to v1:
+ *  - empty pinned-key set ⇒ `{ disabled: true }` (fail-OPEN, unconfigured);
+ *  - keys present but nothing verifies ⇒ `{ ok: false }` (fail-CLOSED);
+ * and it never throws (per-key errors are swallowed inside verifyWithKeys).
+ *
+ * Security: `sigs[]` is attacker-malleable (not in the signed bytes), so trust
+ * comes SOLELY from a real ed25519 verify against a pinned key. Padding with
+ * garbage is inert; stripping every entry is at worst a denial-of-update
+ * (liveness), never a forged accept. keyId is never consulted → no keyId
+ * substitution. Each sig independently binds version/minimum/forceUpdate/
+ * platform-shas, so cross-manifest splicing is blocked exactly as in v1.
+ */
+function verifyWithKeysMulti(message, sigs, keys) {
+    if (keys.length === 0)
+        return { disabled: true };
+    let sawSignature = false;
+    // Bound attacker-supplied work; a real rotation never needs more than a few.
+    for (const entry of sigs.slice(0, MAX_SIGS)) {
+        const sigB64 = typeof entry?.sig === 'string' ? entry.sig : '';
+        if (!sigB64)
+            continue;
+        sawSignature = true;
+        const r = verifyWithKeys(message, sigB64, keys); // keys non-empty ⇒ never {disabled}
+        if ('ok' in r && r.ok)
+            return { ok: true };
+    }
+    return {
+        ok: false,
+        reason: sawSignature
+            ? 'no provided signature verified against any pinned key'
+            : 'missing signature',
+    };
+}
+/**
+ * Verify a single platform artifact's `sig` over buildArtifactMessage(...).
+ * `platform` is the `<platform>-<arch>` key; `version` is the manifest version
+ * the artifact belongs to. Defaults to the baked-in pinned keys.
+ */
+export function verifyArtifact(platform, version, artifact, keys = OVERSKY_RELEASE_PUBLIC_KEYS) {
+    let message;
+    try {
+        message = buildArtifactMessage({
+            platform,
+            version,
+            sha256: artifact.sha256,
+            url: artifact.url,
+        });
+    }
+    catch (err) {
+        // A malformed artifact (missing string fields) must fail-closed as a clean
+        // verification failure, never an uncaught throw.
+        return { ok: false, reason: `malformed artifact: ${err.message}` };
+    }
+    // v2: a present `sigs[]` is authoritative (any-of-N). Otherwise the v1 scalar
+    // path — byte-for-byte the prior behavior.
+    if (Array.isArray(artifact.sigs) && artifact.sigs.length > 0) {
+        return verifyWithKeysMulti(message, artifact.sigs, keys);
+    }
+    return verifyWithKeys(message, artifact.sig, keys);
+}
+/**
+ * Verify the manifest's top-level `sig` over buildManifestMessage(this).
+ * Defaults to the baked-in pinned keys.
+ */
+export function verifyManifest(manifest, keys = OVERSKY_RELEASE_PUBLIC_KEYS) {
+    let message;
+    try {
+        message = buildManifestMessage(manifest);
+    }
+    catch (err) {
+        // A malformed manifest (e.g. a platform entry missing sha256) must
+        // fail-closed as a clean verification failure, never an uncaught throw.
+        return { ok: false, reason: `malformed manifest: ${err.message}` };
+    }
+    // v2: a present `sigs[]` is authoritative (any-of-N). Otherwise the v1 scalar
+    // path — byte-for-byte the prior behavior.
+    if (Array.isArray(manifest.sigs) && manifest.sigs.length > 0) {
+        return verifyWithKeysMulti(message, manifest.sigs, keys);
+    }
+    return verifyWithKeys(message, manifest.sig, keys);
+}
+// ---------------------------------------------------------------------------
+// Differential updates (delta metadata lookup) — UNSIGNED, optimization only.
+// ---------------------------------------------------------------------------
+/**
+ * Look up a delta patch that transforms `fromVersion`'s binary into this
+ * artifact's binary. Returns null when none is advertised or the descriptor is
+ * malformed — the caller then does a full download. PURE; validates shape only
+ * (the delta is UNSIGNED, so trust comes from verifying the RECONSTRUCTED binary
+ * against the signed `artifact.sha256`, not from this metadata).
+ */
+export function getDeltaFor(artifact, fromVersion) {
+    const deltas = artifact.deltas;
+    if (!deltas || typeof deltas !== 'object')
+        return null;
+    const d = deltas[fromVersion];
+    if (!d ||
+        typeof d.url !== 'string' ||
+        typeof d.sha256 !== 'string' ||
+        typeof d.size !== 'number' ||
+        !Number.isFinite(d.size) ||
+        d.size <= 0) {
+        return null;
+    }
+    return d;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/auth-core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Shared auth substrate (token store, refresh, scheduler, fd handoff) for the OverSky daemon and CLI.",
   "type": "module",
   "main": "dist/cjs/index.js",