@skrr-ai/auth-core 0.1.2

package/dist/esm/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Shared types & error classes used across refresh, refreshScheduler, and
+ * fdToken modules. Lives in its own file so consumers can `import type` from
+ * the package without dragging in side-effecting modules.
+ */
+export interface TokenPair {
+    /**
+     * Legacy daemon/cli/web access JWT. Null after Stage-E #1 step 4
+     * for daemon-scope refresh responses: the JWT-daemon substrate has
+     * been retired and only `opaqueAccessToken` is shipped. Non-daemon
+     * scopes (cli, web) still receive a non-null JWT here.
+     */
+    accessToken: string | null;
+    /** Epoch ms. */
+    accessExpiresAt: number;
+    refreshToken: string;
+    /** Epoch ms. */
+    refreshExpiresAt: number;
+    /**
+     * Stage-E #1 — opaque `osk_dmn_*` daemon access token co-issued
+     * with the JWT for daemon-scope sessions. Optional during the
+     * dark-ship migration window:
+     *
+     *   - `undefined` / absent: server didn't co-issue (older API,
+     *     non-daemon scope, or `OVERSKY_DMN_OPAQUE_DISABLED=1` set).
+     *     Daemon authenticates with the JWT (legacy behavior).
+     *   - `null`: server co-issued but the value is explicitly null
+     *     (kill switch tripped mid-rotation, or write failed). Daemon
+     *     callers MUST treat this as "clear any cached opaque slot
+     *     so we don't keep using a stale opaque after its row was
+     *     family-revoked".
+     *   - `string`: opaque plaintext. Daemon stores in keychain and
+     *     prefers over JWT for the next handshake (gated by
+     *     `OVERSKY_PREFER_OPAQUE_DAEMON_TOKEN`, default on).
+     *
+     * Expires in lockstep with `accessExpiresAt` (server-side they're
+     * minted in the same transaction with identical TTL). The pair
+     * intentionally does NOT carry a separate `opaqueAccessExpiresAt`.
+     */
+    opaqueAccessToken?: string | null;
+    /**
+     * Production-hardening 2026-05-06 — soft backoff hint from the server
+     * indicating the fleet refresh-QPS is high and the daemon SHOULD
+     * defer its next proactive refresh by this many seconds (plus its
+     * own jitter). Distinct from a 429 Retry-After: this is advisory,
+     * the rotation already succeeded, and the daemon's correctness is
+     * not at risk if it ignores the hint. Honoring it lets a fleet
+     * stretch its refresh-cadence under load WITHOUT any rejected
+     * requests.
+     *
+     * Sourced from the response's `X-Refresh-Backoff` header (or
+     * `Retry-After` when present on a 200). Absent when the server
+     * isn't backpressuring or the header parser failed.
+     */
+    softBackoffSeconds?: number;
+}
+/**
+ * Server-emitted permanent-failure codes.
+ *
+ * Three groups, all permanent (no amount of retry helps):
+ *   - REFRESH_*       — refresh-token specific (most common path).
+ *   - TOKEN_*         — access-token specific (server pushes 4402 close;
+ *                       daemon classifies as TOKEN_INVALID/TOKEN_EXPIRED).
+ *   - SESSION_REVOKED — admin/forensic revoke; whole family burned.
+ *   - UNKNOWN_401     — server returned 401 with a code we don't
+ *                       recognize. Treated as permanent (better to prompt
+ *                       re-auth than to loop forever) but tagged
+ *                       distinctly so monitoring can surface server-side
+ *                       bugs separately from real expirations.
+ *
+ * Production-hardening 2026-05-06 — widened from the original 4-value
+ * union to include `TOKEN_INVALID`, `TOKEN_EXPIRED`, and `UNKNOWN_401`
+ * to match the codes the daemon and client UX actually emit/render.
+ * Without this, the client `describeAuthFailure` exhaustiveness check
+ * was silently broken for the non-REFRESH branches.
+ */
+export type PermanentAuthReason = 'REFRESH_INVALID' | 'REFRESH_REUSED' | 'REFRESH_EXPIRED' | 'SESSION_REVOKED' | 'TOKEN_INVALID' | 'TOKEN_EXPIRED' | 'UNKNOWN_401';
+export declare class PermanentAuthFailure extends Error {
+    readonly code: PermanentAuthReason;
+    constructor(code: PermanentAuthReason, message: string);
+}
+export declare class TransientAuthFailure extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export interface ReauthState {
+    code: string;
+    message?: string;
+    /** Epoch ms. */
+    at: number;
+}

package/dist/esm/types.js

@@ -0,0 +1,21 @@
+/**
+ * Shared types & error classes used across refresh, refreshScheduler, and
+ * fdToken modules. Lives in its own file so consumers can `import type` from
+ * the package without dragging in side-effecting modules.
+ */
+export class PermanentAuthFailure extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PermanentAuthFailure';
+        this.code = code;
+    }
+}
+export class TransientAuthFailure extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.name = 'TransientAuthFailure';
+        this.cause = cause;
+    }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@skrr-ai/auth-core",
+  "version": "0.1.2",
+  "description": "Shared auth substrate (token store, refresh, scheduler, fd handoff) for the OverSky daemon and CLI.",
+  "type": "module",
+  "main": "dist/cjs/index.js",
+  "module": "dist/esm/index.js",
+  "types": "dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./refresh-classification": {
+      "import": {
+        "types": "./dist/esm/refreshClassification.d.ts",
+        "default": "./dist/esm/refreshClassification.js"
+      },
+      "require": {
+        "types": "./dist/cjs/refreshClassification.d.ts",
+        "default": "./dist/cjs/refreshClassification.js"
+      }
+    }
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "dist/cjs/package.json",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run build:esm && npm run build:cjs && node scripts/finalize-cjs.cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "clean": "rimraf dist",
+    "test": "node --import tsx --test 'src/**/*.test.ts' 'src/**/*.spec.ts'",
+    "test:smoke": "node --import tsx --test 'src/**/*.real-smoke.test.ts'",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2",
+    "tweetnacl": "^1.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.12",
+    "@types/proper-lockfile": "^4.1.4",
+    "rimraf": "^5.0.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "author": "OverSky",
+  "homepage": "https://oversky.ai",
+  "bugs": {
+    "url": "https://github.com/dush1023/OverSky/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dush1023/OverSky.git",
+    "directory": "packages/auth-core"
+  },
+  "keywords": [
+    "oversky",
+    "auth",
+    "cli",
+    "daemon",
+    "token-refresh"
+  ]
+}