@skrr-ai/auth-core 0.1.2

package/dist/esm/credentialEnvelopeBridge.d.ts

@@ -0,0 +1,116 @@
+type CredEnvelopeState = {
+    kind: 'uninit';
+} | {
+    kind: 'disabled';
+    reason: DisabledReason;
+} | {
+    kind: 'active';
+    dek: Buffer;
+    kekId: string;
+    /**
+     * Backend-tier identifier captured at init time
+     * (e.g. `macos-keychain-shellout`, `in-memory-test`). Snapshotted
+     * here so transform-side events can surface the kind without
+     * holding a live `kek` reference.
+     */
+    kekKind: string | null;
+    profile: string;
+};
+type DisabledReason = 'kek_unavailable' | 'init_failed' | 'platform_unsupported' | 'kek_rotated';
+/** @internal Test seam — force-set state, returns previous. */
+export declare function __setStateForTest(next: CredEnvelopeState): CredEnvelopeState;
+/** @internal Test seam — read state for assertions. */
+export declare function __getStateForTest(): CredEnvelopeState;
+/**
+ * Initialize the envelope path. Idempotent — second call when state is
+ * non-uninit returns immediately.
+ *
+ * Order:
+ *   1. Probe KEK; unavailable → disabled+kek_unavailable.
+ *   2. Try to read+unwrap an existing DEK; success → active.
+ *   3. Generate fresh DEK, wrap, persist atomically; → active.
+ *   4. Any throw → disabled+init_failed; transforms stay passthrough.
+ */
+export declare function initCredEnvelope(profile: string): Promise<void>;
+/**
+ * Reset state. With `clearOnDisk` deletes the wrapped DEK file too —
+ * used by `oversky logout` / `sky logout`. Zeroes the in-memory DEK
+ * before dropping state for forward secrecy on the active credential.
+ */
+export declare function resetCredEnvelope(opts?: {
+    profile?: string;
+    clearOnDisk?: boolean;
+}): Promise<void>;
+export declare function shutdownCredEnvelope(): void;
+/** @internal Test seam — re-arm `shutdownCredEnvelope` so it can run again. */
+export declare function __resetShutdownGuardForTest(): void;
+/**
+ * True iff the envelope path is initialized AND active. Hot-path
+ * predicate used by sync transforms; never throws.
+ */
+export declare function isCredEnvelopeActive(): boolean;
+/**
+ * Operator-readable summary of envelope state. Used by `oversky status`
+ * and CLI debug commands. Never includes the DEK or any key material.
+ *
+ * `kekRotated` is true when the most recent init pass detected a wrapped
+ * DEK that could not be unwrapped under the currently-available KEK and
+ * had to fall back to a fresh enrollment. Operators see this in
+ * `oversky status`; clears on the next clean `resetCredEnvelope`.
+ */
+export declare function describeCredEnvelopeState(): {
+    kind: CredEnvelopeState['kind'];
+    reason?: DisabledReason;
+    kekId?: string;
+    kekKind?: string | null;
+    profile?: string;
+    kekRotated?: boolean;
+};
+/**
+ * Sync write transform. Returns the wrapped serialized form when active.
+ *
+ * Behavior when not active:
+ *   - If `credEnvelopeFailClosed` was set via `configureAuthCore()` (or
+ *     `OVERSKY_KEK_REQUIRED=1` is set as a back-compat trigger), emits
+ *     `cred_envelope.wrap.refused` and throws — the caller must not
+ *     write plaintext.
+ *   - Otherwise, returns the plaintext (legacy fail-open behavior used
+ *     by CLI today during dark-ship rollout).
+ *
+ * Empty-string input is universally passthrough — there is no secret
+ * to protect.
+ */
+export declare function maybeEncryptForWrite(plaintext: string): string;
+/**
+ * Always-fail-open variant of `maybeEncryptForWrite` for callers that
+ * cannot afford to abort their write when the envelope path is inactive
+ * (today: device-identity persistence, which writes the private key as
+ * plaintext JSON before the L12 KEK ships per-platform). The wire form
+ * is identical to `maybeEncryptForWrite` when active (envelope-prefixed)
+ * and identical to the input when not.
+ *
+ * Distinct from `maybeEncryptForWrite` because that helper honors the
+ * daemon's `credEnvelopeFailClosed: true` policy — designed for callers
+ * that MUST refuse a plaintext write rather than silently degrade.
+ */
+export declare function wrapIfActiveOrPassthrough(plaintext: string): string;
+/**
+ * Sync read transform. Three cases:
+ *   1. Envelope on disk + path active → decrypt; null on tag mismatch
+ *      (caller treats null as a forced re-login signal).
+ *   2. Envelope on disk + path NOT active → null (rolled-back binary
+ *      while envelopes are persisted).
+ *   3. Legacy plaintext → return as-is; if path is active, set
+ *      `needsMigration=true` so caller can upgrade in place.
+ */
+export interface ReadTransformResult {
+    /** Decoded plaintext, or null on hard failure. */
+    plaintext: string | null;
+    /** True when the on-disk form was legacy plaintext AND the envelope
+     *  path is active — caller should re-write to upgrade. */
+    needsMigration: boolean;
+}
+export declare function maybeDecryptOnRead(stored: string): ReadTransformResult;
+/** @internal Test seam — wrapped-DEK path resolver. */
+export declare function __wrappedDekFilePathForTest(profile: string): string;
+export {};