@skrr-ai/auth-core 0.1.2

package/dist/cjs/credentialResolver.js

@@ -0,0 +1,423 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CredentialResolver = exports.AuthHelperUntrustedError = exports.AuthHelperUnavailableError = exports.CI_TOKEN_PREFIX = exports.CREDENTIAL_PRECEDENCE = void 0;
+exports.classifyTokenKind = classifyTokenKind;
+exports.__resetCredentialResolverForTest = __resetCredentialResolverForTest;
+exports.invalidateAuthHelperCache = invalidateAuthHelperCache;
+/**
+ * credentialResolver.ts — documented credential precedence for the
+ * OverSky daemon and CLI.
+ *
+ * Roadmap: docs/daemon-auth-roadmap.md, Phase H.
+ *
+ * The resolver walks a fixed, ordered list of credential sources and
+ * returns the first non-null token along with its source name. Source
+ * names are part of the public surface — they show up in
+ * `oversky doctor`, `oversky status`, and `sky whoami`, and operators
+ * use them to triage "where did this token come from?" tickets.
+ *
+ * Precedence (high → low):
+ *
+ *   1. flag         — `--token <jwt>` CLI flag (debugging)
+ *   2. env-token    — `OVERSKY_TOKEN` env (CI / static; Phase I adds
+ *                     server-side scope=ci validation)
+ *   3. auth-helper  — `OVERSKY_AUTH_HELPER` script output (rotating
+ *                     creds — Vault, AWS SM, internal SSO proxy)
+ *   4. fd-handoff   — `OVERSKY_AUTH_FD` parent→child IPC (Electron
+ *                     supervisor → daemon child). Internal; never
+ *                     user-configured.
+ *   5. keychain     — macOS Keychain (`ai.skrr.daemon`)
+ *   6. file         — `~/.skrr/auth.json` (0600)
+ *   7. interactive  — Browser/device-code login (TTY only, blocked
+ *                     under launchd via `isHeadless()`)
+ *
+ * Skip rules (Phase H.2 + H.4):
+ *   - `bareMode: true` skips slots 4–7 (no platform storage, no IPC,
+ *     no interactive). Bare mode demands an explicit token from env or
+ *     flag — designed for reproducible CI runs and "is the daemon
+ *     broken or is my config corrupted?" triage.
+ *   - `storeMode: 'env-only'` skips slots 5 + 6 (and the daemon
+ *     wrapper additionally disables the auth-generation.json sidecar).
+ *   - `storeMode: 'keychain'` skips slot 6 (file backend).
+ *   - `storeMode: 'file'` skips slot 5 (keychain backend).
+ *
+ * Backend access uses dependency-injected callbacks
+ * (`readKeychainToken`, `readFileToken`, `runInteractiveLogin`) so this
+ * module stays free of OS-specific imports and the Sky CLI can wire its
+ * own backends without dragging the daemon's `keychain.ts` into
+ * non-daemon binaries.
+ */
+const authHelper_js_1 = require("./authHelper.js");
+const fdToken_js_1 = require("./fdToken.js");
+const jwtUtils_js_1 = require("./jwtUtils.js");
+const runtime_js_1 = require("./runtime.js");
+/**
+ * Ordered slots tried by `CredentialResolver.resolve()`. Excludes
+ * `'none'` (only emitted when no slot produced a token). Treat this as
+ * the canonical published precedence — flipping the order is a public
+ * API change and breaks operator runbooks.
+ */
+exports.CREDENTIAL_PRECEDENCE = [
+    'flag',
+    'env-token',
+    'auth-helper',
+    'fd-handoff',
+    'keychain',
+    'file',
+    'interactive',
+];
+/** CI-token plaintext prefix; mirrors api/server/services/Auth/daemonCiTokens.js. */
+exports.CI_TOKEN_PREFIX = 'osk_ci_';
+/**
+ * Classify a token by local shape. Pure function; safe to call on any string
+ * (including `null`-coerced empty). Returns `'standard'` for empty input
+ * so callers don't need to null-check before classification.
+ *
+ * Honors `OVERSKY_DISABLE_CI_TOKEN_RESOLVER=1` kill switch — when set,
+ * everything classifies as `'standard'` so the resolver can be used as
+ * a triage tool ("is the CI-token path the problem?").
+ */
+/**
+ * SECURITY NOTE — this reads `scope` out of an UNVERIFIED JWT payload.
+ *
+ * That is safe here, and stays safe only under one condition: the return value
+ * selects a local code path and nothing else. `'install'` means "refresh this
+ * the install-token way"; it grants no capability, skips no check, and asserts
+ * no identity. The server still validates the token on every request, so a
+ * forged `scope: daemon-install` buys an attacker a different local branch and
+ * the same 401.
+ *
+ * The forgery is trivial — no signature is checked, so anyone who can write the
+ * credential file or set the env var can put any claim in it. That is fine
+ * while the only consequence is routing. It stops being fine the moment a
+ * caller treats `TokenKind` as a permission. Do not let this value gate a
+ * capability, and do not add a branch here that returns a kind meaning "more
+ * privileged".
+ *
+ * See `jwtUtils.ts` for the general rule.
+ */
+function classifyTokenKind(token) {
+    if (process.env.OVERSKY_DISABLE_CI_TOKEN_RESOLVER === '1')
+        return 'standard';
+    if (typeof token !== 'string' || token.length === 0)
+        return 'standard';
+    if (token.startsWith(exports.CI_TOKEN_PREFIX))
+        return 'ci';
+    const payload = (0, jwtUtils_js_1.decodeJwtPayload)(token);
+    if (payload &&
+        typeof payload === 'object' &&
+        !Array.isArray(payload) &&
+        payload.scope === 'daemon-install') {
+        return 'install';
+    }
+    return 'standard';
+}
+let _helperCache = null;
+/** @internal test-only — drop the helper cache between tests. */
+function __resetCredentialResolverForTest() {
+    _helperCache = null;
+}
+/**
+ * L6.3 — typed error thrown when the cold-cache failure sentinel is in
+ * effect. Callers (daemon refresh path, CLI) can catch this specifically
+ * to render "auth helper unavailable: <reason>" without falling through
+ * to OAuth or device-code retry.
+ */
+class AuthHelperUnavailableError extends Error {
+    reason;
+    cachedAt;
+    constructor(reason, cachedAt) {
+        super(`auth helper unavailable: ${reason}`);
+        this.name = 'AuthHelperUnavailableError';
+        this.reason = reason;
+        this.cachedAt = cachedAt;
+    }
+}
+exports.AuthHelperUnavailableError = AuthHelperUnavailableError;
+/**
+ * L6.1 — typed error thrown when the workspace-trust gate blocks a
+ * project- or local-scope helper. Surfaces the actionable next step
+ * (`oversky trust accept`) to the user; the daemon catches and presents
+ * this without falling through to OAuth.
+ */
+class AuthHelperUntrustedError extends Error {
+    origin;
+    reason;
+    helperPath;
+    constructor(helperPath, origin, reason) {
+        super(`OVERSKY_AUTH_HELPER (${origin}-scope) is not trusted for this workspace ` +
+            `(reason: ${reason}). Run \`oversky trust accept\` to allow it.`);
+        this.name = 'AuthHelperUntrustedError';
+        this.origin = origin;
+        this.reason = reason;
+        this.helperPath = helperPath;
+    }
+}
+exports.AuthHelperUntrustedError = AuthHelperUntrustedError;
+/**
+ * H3-6 — public invalidation seam for the `OVERSKY_AUTH_HELPER` result
+ * cache. 401 handlers call this right after receiving a 401 from the
+ * server so the NEXT credential resolve re-invokes the helper to mint
+ * a fresh token instead of serving the stale (cached) one for up to
+ * `OVERSKY_AUTH_HELPER_TTL_MS`.
+ *
+ * Without this seam, a rotated secret at the helper's source (Vault,
+ * AWS Secrets Manager, etc.) could take up to 5 minutes to propagate
+ * to OverSky even when the server is actively rejecting the old
+ * value. The helper is the only slot in the precedence chain that
+ * naturally caches; keychain/file reads are already one-shot per
+ * resolve.
+ *
+ * L6.3 — also clears the cold-cache failure sentinel. A 401 means the
+ * server is rejecting whatever we sent, which usually means the helper
+ * needs to retry from scratch — even when the LAST helper attempt
+ * failed and seeded the sentinel. Without this, a transient helper
+ * failure during the same TTL window as a server-issued 401 would lock
+ * the daemon out for the full TTL.
+ *
+ * Idempotent: calling this on an already-empty cache is a no-op.
+ */
+function invalidateAuthHelperCache() {
+    _helperCache = null;
+}
+class CredentialResolver {
+    opts;
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /**
+     * Walk the precedence chain and return the first non-null token.
+     * Returns `{ token: null, source: 'none' }` when nothing matches.
+     *
+     * Fail-closed exceptions from the auth-helper slot
+     * (`AuthHelperUntrustedError`, `AuthHelperUnavailableError`) propagate
+     * out — they intentionally PREVENT fall-through to OAuth. Callers
+     * that want soft-fall-through behavior must catch explicitly. See
+     * L6.1 spec point 4 and L6.3.
+     */
+    async resolve() {
+        for (const source of exports.CREDENTIAL_PRECEDENCE) {
+            if (this.shouldSkip(source))
+                continue;
+            const token = await this.tryResolveSlot(source);
+            if (token) {
+                return { token, source, kind: classifyTokenKind(token) };
+            }
+        }
+        return { token: null, source: 'none', kind: 'standard' };
+    }
+    /**
+     * Test seam: invoke a single slot in isolation. Production code should
+     * always go through `resolve()` so the chain ordering is enforced.
+     */
+    async tryResolveSlot(source) {
+        switch (source) {
+            case 'flag':
+                return this.tryResolveFlag();
+            case 'env-token':
+                return this.tryResolveEnvToken();
+            case 'auth-helper':
+                return this.tryResolveAuthHelper();
+            case 'fd-handoff':
+                return this.tryResolveFdHandoff();
+            case 'keychain':
+                return this.tryResolveKeychain();
+            case 'file':
+                return this.tryResolveFile();
+            case 'interactive':
+                return this.tryResolveInteractive();
+        }
+    }
+    shouldSkip(source) {
+        const { bareMode } = this.opts;
+        const storeMode = this.opts.storeMode ?? 'auto';
+        if (bareMode &&
+            (source === 'fd-handoff' ||
+                source === 'keychain' ||
+                source === 'file' ||
+                source === 'interactive')) {
+            return true;
+        }
+        if (storeMode === 'env-only' && (source === 'keychain' || source === 'file')) {
+            return true;
+        }
+        if (storeMode === 'keychain' && source === 'file')
+            return true;
+        if (storeMode === 'file' && source === 'keychain')
+            return true;
+        return false;
+    }
+    // ------------------------------------------------------------------
+    // Slot implementations
+    // ------------------------------------------------------------------
+    tryResolveFlag() {
+        const v = this.opts.flagToken;
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    }
+    tryResolveEnvToken() {
+        if (this.opts.envTokenOverride === null)
+            return null; // explicit force-skip
+        if (typeof this.opts.envTokenOverride === 'string') {
+            return this.opts.envTokenOverride.length > 0 ? this.opts.envTokenOverride : null;
+        }
+        const v = process.env.OVERSKY_TOKEN;
+        return typeof v === 'string' && v.length > 0 ? v : null;
+    }
+    async tryResolveAuthHelper() {
+        let helperPath;
+        let fromEnvVar = false;
+        if (this.opts.authHelperPathOverride === null)
+            return null;
+        if (typeof this.opts.authHelperPathOverride === 'string') {
+            helperPath =
+                this.opts.authHelperPathOverride.length > 0 ? this.opts.authHelperPathOverride : null;
+        }
+        else {
+            helperPath = process.env.OVERSKY_AUTH_HELPER ?? null;
+            fromEnvVar = helperPath !== null;
+        }
+        if (!helperPath)
+            return null;
+        // ---------------------------------------------------------------
+        // L6.3 — sentinel served BEFORE re-spawning. Failure cache prevents
+        // silent fall-through to OAuth within the TTL window.
+        // ---------------------------------------------------------------
+        if (_helperCache && Date.now() < _helperCache.expiresAt) {
+            if (_helperCache.kind === 'success') {
+                return _helperCache.token;
+            }
+            // Failed sentinel still warm — fail closed. The slot returns
+            // a fail-closed signal via thrown error so the chain doesn't
+            // continue to keychain/file/OAuth.
+            this.opts.onAuthHelperSentinelHit?.({
+                helperPath,
+                reason: _helperCache.reason,
+                cachedAt: _helperCache.cachedAt,
+                ttlMs: _helperCache.expiresAt - _helperCache.cachedAt,
+            });
+            throw new AuthHelperUnavailableError(_helperCache.reason, _helperCache.cachedAt);
+        }
+        // ---------------------------------------------------------------
+        // L6.1 — workspace-trust gate. Project- and local-scope helpers
+        // must have an accepted trust record for the cwd. User-scope
+        // helpers (env var, ~/.skrr/) bypass the check.
+        //
+        // Trust check runs BEFORE invocation so we never even spawn an
+        // untrusted script. Failed trust = fail-closed throw, never
+        // falls through to OAuth.
+        // ---------------------------------------------------------------
+        if (this.opts.helperTrustGate) {
+            const decision = this.opts.helperTrustGate(helperPath, fromEnvVar);
+            if (!decision.trusted) {
+                const reason = decision.reason ?? 'no-record';
+                this.opts.onAuthHelperBlocked?.({
+                    helperPath,
+                    origin: decision.origin,
+                    reason,
+                    cwd: process.cwd(),
+                });
+                throw new AuthHelperUntrustedError(helperPath, decision.origin, reason);
+            }
+        }
+        const result = await (0, authHelper_js_1.invokeAuthHelper)(helperPath);
+        if (result) {
+            const ttlMs = (0, authHelper_js_1.getDefaultHelperTtlMs)();
+            const expiresAt = result.expiresAt ?? Date.now() + ttlMs;
+            _helperCache = { kind: 'success', token: result.token, expiresAt };
+            return result.token;
+        }
+        // ---------------------------------------------------------------
+        // L6.3 — invocation failed. Distinguish two failure classes:
+        //
+        //   - Validation failures ('disabled', 'invalid-path',
+        //     'not-executable', null) — helper isn't really wired up.
+        //     Fall through to next slot. NO sentinel.
+        //
+        //   - Execution failures ('timeout', 'non-zero-exit', 'oversized',
+        //     'empty-output', 'parse-error', 'spawn-error') — the helper
+        //     was wired up but couldn't deliver a token. Cache the
+        //     sentinel and fail closed for the TTL window. This matches
+        //     CC's `' '` literal sentinel at CC-A-34.
+        // ---------------------------------------------------------------
+        const reason = (0, authHelper_js_1.getLastAuthHelperFailureReason)();
+        if (reason && authHelper_js_1.SENTINEL_TRIGGERING_FAILURES.has(reason)) {
+            const ttlMs = (0, authHelper_js_1.getDefaultHelperTtlMs)();
+            const cachedAt = Date.now();
+            _helperCache = {
+                kind: 'failed',
+                reason,
+                cachedAt,
+                expiresAt: cachedAt + ttlMs,
+            };
+            this.opts.onAuthHelperSentinelHit?.({
+                helperPath,
+                reason,
+                cachedAt,
+                ttlMs,
+            });
+            throw new AuthHelperUnavailableError(reason, cachedAt);
+        }
+        // Validation failure — no sentinel; fall through.
+        return null;
+    }
+    async tryResolveFdHandoff() {
+        // FD handoff is daemon-only; CLI never has OVERSKY_AUTH_FD set, so
+        // the env check below makes this a near-zero-cost slot for CLI
+        // processes. The fdToken module does its own kill-switch check
+        // (`fdTokenHandoff` killSwitch) and bounded read.
+        if (!process.env.OVERSKY_AUTH_FD)
+            return null;
+        try {
+            const payload = await (0, fdToken_js_1.readAuthFromFd)();
+            if (!payload)
+                return null;
+            if (payload.accessExpiresAt && Date.now() > payload.accessExpiresAt) {
+                return null;
+            }
+            return payload.accessToken || null;
+        }
+        catch (err) {
+            (0, runtime_js_1.getAuthLogger)().warn(`[credentialResolver] FD handoff read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    tryResolveKeychain() {
+        if (!this.opts.readKeychainToken)
+            return null;
+        try {
+            return this.opts.readKeychainToken();
+        }
+        catch (err) {
+            (0, runtime_js_1.getAuthLogger)().warn(`[credentialResolver] keychain read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    tryResolveFile() {
+        if (!this.opts.readFileToken)
+            return null;
+        try {
+            return this.opts.readFileToken();
+        }
+        catch (err) {
+            (0, runtime_js_1.getAuthLogger)().warn(`[credentialResolver] file read failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+    async tryResolveInteractive() {
+        if (!this.opts.runInteractiveLogin)
+            return null;
+        if (this.opts.isHeadless?.())
+            return null;
+        try {
+            return await this.opts.runInteractiveLogin();
+        }
+        catch (err) {
+            (0, runtime_js_1.getAuthLogger)().warn(`[credentialResolver] interactive login failed: ${formatErr(err)}`);
+            return null;
+        }
+    }
+}
+exports.CredentialResolver = CredentialResolver;
+function formatErr(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/cjs/daemonPair.d.ts

@@ -0,0 +1,172 @@
+/** Box nonce length per RFC 8439 / NaCl. */
+export declare const PAIR_NONCE_LEN = 24;
+/** Curve25519 public key length. */
+export declare const PAIR_PUBKEY_LEN = 32;
+/** Curve25519 secret key length. */
+export declare const PAIR_SECRET_LEN = 32;
+/** Big-endian uint16 length prefix for the AAD trailer. */
+export declare const PAIR_AAD_LEN_PREFIX = 2;
+/** Server validator caps `encryptedPayload` at 8192 chars (base64). */
+export declare const PAIR_BUNDLE_MAX_BASE64_LEN = 8192;
+/** Conservative ceiling on the trailer to keep the bundle well under cap. */
+export declare const PAIR_AAD_MAX_LEN = 1024;
+/** AAD prefix — version-bumped on any breaking format change. */
+export declare const PAIR_AAD_PREFIX = "oversky:pair:v1";
+export type PairBundleErrorCode = 'BUNDLE_TOO_SHORT' | 'BUNDLE_TOO_LONG' | 'BUNDLE_BAD_BASE64' | 'AAD_LEN_OVERFLOW' | 'AAD_LEN_UNDERFLOW' | 'AAD_MISMATCH' | 'DECRYPT_FAILED' | 'PLAINTEXT_NOT_JSON' | 'PLAINTEXT_BAD_SHAPE' | 'DAEMON_ID_MISMATCH' | 'INVALID_KEY';
+export declare class PairBundleError extends Error {
+    readonly code: PairBundleErrorCode;
+    constructor(code: PairBundleErrorCode, message: string);
+}
+/**
+ * Plaintext shape sealed inside the box. Versioned via `v` so future
+ * additions (e.g. data-encryption-key for L12 envelope handoff) extend
+ * the schema without breaking older daemons.
+ *
+ * `token` is optional because Stage-E #1 step 4 daemon-scope mints ship
+ * `opaqueAccessToken` only (no JWT). At least one of `token` or
+ * `opaqueAccessToken` MUST be present, enforced in `parsePairPlaintext`.
+ */
+export interface PairPlaintextV1 {
+    v: 1;
+    /** Daemon-scope JWT — optional after Stage-E #1 step 4. */
+    token?: string;
+    /** Access token expiry (epoch ms). */
+    expiresAt?: number;
+    /** Rotating refresh token. */
+    refreshToken?: string;
+    /** Refresh token expiry (epoch ms). */
+    refreshExpiresAt?: number;
+    /** Stage-E #1 — opaque `osk_dmn_*` daemon access token. */
+    opaqueAccessToken?: string;
+    /**
+     * The daemonId the credentials were minted for. Daemon MUST verify
+     * this matches the `daemonId` it advertised in the QR — guards against
+     * a misdirected /respond targeting a different daemon's pairing row.
+     */
+    daemonId: string;
+    /** Mobile-side issuance time (epoch ms). For audit/log only. */
+    issuedAt: number;
+}
+export interface PairBundle {
+    /** Raw 24-byte nonce. */
+    nonce: Uint8Array;
+    /** Raw 32-byte mobile ephemeral public key. */
+    ephemeralPublicKey: Uint8Array;
+    /** Box ciphertext (plaintext + Poly1305 tag). */
+    ciphertext: Uint8Array;
+    /** Canonical AAD bytes — SHOULD match the rebuilt AAD on verify. */
+    aad: Uint8Array;
+}
+/**
+ * Build the canonical AAD bytes for a pairing response. Both sides
+ * (mobile-builder and daemon-verifier) call this with identical inputs:
+ *   - mobile gets `responseUserId` from its own JWT (`req.user.id`)
+ *   - daemon gets `responseUserId` from the `/poll` response
+ *
+ * The encoding is ASCII; non-ASCII inputs are rejected so a hostile
+ * daemonId/userId can't smuggle bytes that would shift the boundary.
+ */
+export declare function buildPairAad(daemonId: string, responseUserId: string): Uint8Array;
+/**
+ * Parse and validate the JSON plaintext that came out of the box. We
+ * keep this tolerant on output (older daemons may write extra fields)
+ * but strict on the invariant fields the daemon needs to persist.
+ */
+export declare function parsePairPlaintext(raw: unknown): PairPlaintextV1;
+export interface AssembleBundleOptions {
+    /** Plaintext to seal — JSON-stringified before boxing. */
+    plaintext: PairPlaintextV1;
+    /** Daemon's ephemeral X25519 public key (32 bytes). */
+    daemonPublicKey: Uint8Array;
+    /** Mobile's ephemeral X25519 secret key (32 bytes). */
+    ephemeralSecretKey: Uint8Array;
+    /** Mobile's ephemeral X25519 public key (32 bytes), echoed into bundle. */
+    ephemeralPublicKey: Uint8Array;
+    /** Canonical AAD bytes from `buildPairAad`. */
+    aad: Uint8Array;
+    /**
+     * Override the random nonce — for tests only. Production callers must
+     * leave this undefined so a fresh nonce is generated.
+     */
+    __nonceForTest?: Uint8Array;
+}
+/**
+ * Mobile-side: encrypt the plaintext to the daemon's pubkey and frame
+ * the result for transport. Returns base64-encoded bundle suitable for
+ * the `encryptedPayload` field of `POST /api/auth/pair/respond`.
+ */
+export declare function assemblePairBundleBase64(opts: AssembleBundleOptions): string;
+/**
+ * Parse the wire bytes into a `PairBundle` without decrypting. Used as
+ * a preflight by `openPairBundleBase64` and exposed for tests.
+ */
+export declare function parsePairBundle(bytes: Uint8Array): PairBundle;
+export interface OpenBundleOptions {
+    /** Base64 wire payload from `/poll`'s `response` field. */
+    encryptedPayloadBase64: string;
+    /** Daemon's ephemeral X25519 secret key. */
+    daemonSecretKey: Uint8Array;
+    /**
+     * Canonical AAD bytes the daemon expects, rebuilt from `daemonId` +
+     * `responseUserId` returned by the /poll response.
+     */
+    expectedAad: Uint8Array;
+    /**
+     * The daemonId the daemon advertised in its QR. We verify the
+     * decrypted plaintext echoes the SAME id, in addition to the AAD
+     * trailer the server bound. Belt-and-suspenders.
+     */
+    expectedDaemonId: string;
+}
+/**
+ * Daemon-side: parse, AAD-verify, decrypt, JSON-parse, validate the
+ * pairing response. Returns the validated plaintext on success; throws
+ * `PairBundleError` on any failure.
+ *
+ * Constant-time-ish AAD comparison: tweetnacl's box.open already runs
+ * Poly1305 in constant time, and the AAD compare we do is byte-by-byte
+ * on a 1KB-bounded buffer — short side-channel exposure is negligible
+ * given we're comparing public-known canonical bytes.
+ */
+export declare function openPairBundleBase64(opts: OpenBundleOptions): PairPlaintextV1;
+export interface PairUrlFields {
+    /** 32-byte daemon ephemeral public key, base64url no-pad. */
+    publicKeyBase64Url: string;
+    /** Server-issued pair id, hex. */
+    pairId: string;
+    /** Daemon id (free-form, ASCII, ≤128 chars). */
+    daemonId: string;
+    /**
+     * User-friendly machine label so the mobile can show "Approve pairing
+     * with MacBook-Pro?" — purely UX, not security-bearing.
+     */
+    host?: string;
+    /** Server URL the daemon is paired against, for split-deployment hints. */
+    serverUrl?: string;
+    /**
+     * Wire-format protocol version. Bump on any breaking change to the
+     * bundle layout or AAD canonical form.
+     */
+    v?: number;
+}
+/**
+ * Build the URL the daemon prints as a QR code. URL-safe parameters
+ * only; the bulk is the public key, which is fine.
+ */
+export declare function buildPairUrl(fields: PairUrlFields): string;
+/**
+ * Parse a scanned URL back into structured fields. Returns null on any
+ * format error so the caller can show a user-friendly "not a pair QR"
+ * message rather than a stack trace. Strict validation of every field's
+ * shape keeps a hostile QR from steering the mobile at a bad daemonId.
+ */
+export declare function parsePairUrl(url: string): PairUrlFields | null;
+export declare function uint8ArrayToBase64(bytes: Uint8Array): string;
+export declare function base64ToUint8Array(b64: string): Uint8Array;
+export declare function uint8ArrayToBase64Url(bytes: Uint8Array): string;
+export declare function base64UrlToUint8Array(b64url: string): Uint8Array;
+export interface PairKeyPair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+}
+export declare function generatePairKeyPair(): PairKeyPair;