/**
 * JIT layer-2 tools — run identity + offload handle crypto.
 *
 * A handle is {ref, access_token, expire_at}:
 *   - ref          = tm://runs/{run_id}/steps/{step_id}/result
 *   - access_token = HMAC-SHA256(store-persisted key, run_id)
 *     (may also ride the ref as a `#<hex>` fragment — tm_fetch accepts both)
 *   - expire_at    = creation time + TM_BLACKBOARD_TTL (default 7 days)
 *
 * The key is PERSISTED at the store root (`.handle-key`, 32 random bytes,
 * created once with the `wx` flag so two first-boot processes cannot clobber
 * each other).  A model can carry a handle around but cannot forge one for
 * another run, and — because the payload is on disk and the key outlives the
 * process — a handle issued before a plugin restart is still fetchable
 * afterwards.  A corrupt/unreadable key file falls back to the old
 * per-process random key, and the caller records that in the trajectory
 * (never a silent "all handles dead").
 */
import * as crypto from "node:crypto";
/** Compact run id: `r-<yyyyMMdd-HHmmss>-<6 hex>` (generated once per server()). */
export declare function newRunId(now?: Date): string;
/** HMAC-SHA256(key, runId) as hex — the handle access token. */
export declare function hmacToken(key: crypto.BinaryLike, runId: string): string;
/** Constant-time token check (length-compare guard before timingSafeEqual). */
export declare function verifyToken(key: crypto.BinaryLike, runId: string, token: unknown): boolean;
/** Strict ref grammar; the token fragment is optional. */
export declare const REF_PATTERN: RegExp;
export declare function buildRef(runId: string, stepId: string): string;
export interface ParsedRef {
    runId: string;
    stepId: string;
    token?: string;
}
/** Parse a ref; null when malformed (wrong scheme, extra segments, junk). */
export declare function parseRef(ref: unknown): ParsedRef | null;
/**
 * True when `expireAt` (ms epoch) is strictly in the past at `now`.
 * Non-numeric expire_at fails CLOSED (treated as expired) — entries are
 * plugin-written, so a malformed one must not extend a handle's life.
 */
export declare function isExpired(expireAt: unknown, now?: number): boolean;
/** File name of the persisted handle-signing key, at the store root. */
export declare const HANDLE_KEY_FILE = ".handle-key";
export interface HandleKeyResult {
    key: Buffer;
    /** `persisted` = created at / read back from the store root; `ephemeral` = per-process fallback. */
    source: "persisted" | "ephemeral";
    /** Why the persisted key was unusable (an errno code or "corrupt" — never key material). */
    reason?: string;
}
/**
 * Load the store's handle-signing key, creating it on first boot.
 *
 * `wx` is the concurrency guard: two processes starting together both try to
 * create, exactly one wins, the loser reads the winner's key back — an
 * existing key is NEVER overwritten (overwriting would invalidate every
 * handle the other process just issued).  Any failure (unwritable dir,
 * unreadable/corrupt file) degrades to a per-process random key with a
 * machine-readable reason; the caller must surface `source` in the
 * trajectory so the degradation is visible instead of silently killing
 * every cross-process handle.
 */
export declare function loadOrCreateHandleKey(dir: string): HandleKeyResult;
//# sourceMappingURL=refs.d.ts.map