@skrr-ai/auth-core 0.1.2

package/dist/esm/deviceKey.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Ed25519 JSON Web Key — RFC 8037 §2 ("Key Type 'OKP'").
+ *
+ * `x` is the 32-byte public point in base64url-no-padding. `d` is the
+ * 32-byte private scalar; only present in the private JWK and must NEVER
+ * cross the trust boundary (server, log file, dashboard, or backup).
+ */
+export interface Ed25519PublicJwk {
+    readonly kty: 'OKP';
+    readonly crv: 'Ed25519';
+    readonly x: string;
+}
+export interface Ed25519PrivateJwk extends Ed25519PublicJwk {
+    readonly d: string;
+}
+/**
+ * The full keypair returned at generation time. Holding both forms here
+ * is convenient for the daemon-side bridge — the public form is what we
+ * publish; the private form is what we sign with.
+ *
+ * `thumbprint` is the RFC 7638 JWK thumbprint of the public key — the
+ * canonical stable id we use as the device handle on the server.
+ */
+export interface DeviceKeyPair {
+    readonly publicJwk: Ed25519PublicJwk;
+    readonly privateJwk: Ed25519PrivateJwk;
+    readonly thumbprint: string;
+}
+/**
+ * Generate a fresh Ed25519 keypair. Uses Node's native bindings —
+ * `crypto.generateKeyPairSync('ed25519')` is available since Node 12 and
+ * is the same primitive `crypto.sign(null, ..., privateKey)` consumes.
+ *
+ * Output is the JWK form (RFC 8037) so callers can serialize directly
+ * without dealing with PKCS#8 or raw byte representations. The private
+ * scalar `d` and public point `x` are 32 bytes each.
+ */
+export declare function generateDeviceKeyPair(): DeviceKeyPair;
+/**
+ * RFC 7638 JWK Thumbprint — SHA-256 of the canonical JSON of the
+ * required members. For an OKP key those are `crv`, `kty`, and `x`,
+ * lexicographically ordered with no whitespace.
+ *
+ * Stable across implementations: a server that derives the thumbprint
+ * the same way always agrees with us. This is the value we use as the
+ * `kid` in JWS headers and as the registered identifier on the server's
+ * `Daemon` table.
+ */
+export declare function jwkThumbprint(publicJwk: Ed25519PublicJwk): string;
+/**
+ * Construct an `Ed25519PublicJwk` from a base64url-encoded 32-byte
+ * public point. Used by the persistence layer when reading a stored
+ * public key; rejects garbage so a corrupted JWK file fails loudly
+ * rather than producing a silently-broken signing key.
+ */
+export declare function publicJwkFromX(x: string): Ed25519PublicJwk;
+/**
+ * `ath` / `rth` claim value: SHA-256 of the token ASCII bytes,
+ * base64url-encoded (no padding). Must match exactly on both sides.
+ */
+export declare function tokenHash(token: string): string;
+/**
+ * Normalize a URL for the `htu` claim per RFC 9449 §4.2:
+ *   - strip query string
+ *   - strip fragment
+ *   - strip userinfo
+ *   - lowercase scheme and host
+ *
+ * The path is left as-is (case-sensitive per RFC 3986). Trailing slash
+ * is preserved — the server compares to its own normalized form so as
+ * long as both sides use the same rule the comparison holds.
+ */
+export declare function normalizeHtu(url: string): string;
+export interface DeviceProofClaims {
+    /** HTTP method, uppercase. */
+    htm: string;
+    /** Normalized HTTP URI, see `normalizeHtu`. */
+    htu: string;
+    /** Issued-at, seconds since epoch. */
+    iat: number;
+    /** Unique nonce per signature. Server tracks recently-seen jti for
+     *  replay defense within the iat window. */
+    jti: string;
+    /** SHA-256 of the refresh token. Set on refresh requests. */
+    rth?: string;
+    /** SHA-256 of the access token. Set on resource-access requests. */
+    ath?: string;
+}
+export interface DeviceProofHeader {
+    alg: 'EdDSA';
+    /** Custom `typ` so the server can refuse generic JWTs that happen
+     *  to be EdDSA-signed by a stolen device key. RFC 9449 uses
+     *  `dpop+jwt`; we differentiate so OverSky proofs can't be
+     *  cross-replayed into a generic DPoP resource server. */
+    typ: 'oversky-dpop+jwt';
+    jwk: Ed25519PublicJwk;
+}
+export interface BuildProofOptions {
+    method: string;
+    url: string;
+    /** Plaintext refresh token. Hashed inline; the token itself is not
+     *  carried in the proof. */
+    refreshToken?: string;
+    /** Plaintext access token. Hashed inline. */
+    accessToken?: string;
+    /** Override iat (seconds). Useful for tests; production should leave
+     *  unset so the wall clock is used. */
+    iat?: number;
+    /** Override jti. Useful for tests; production should leave unset so
+     *  a fresh 16-byte random is generated. */
+    jti?: string;
+}
+/**
+ * Build a JWS Compact Serialization device-identity proof.
+ *
+ * Header includes the public JWK inline (RFC 9449 pattern) so the
+ * server can verify the signature without prior key lookup, then
+ * additionally check that the inlined JWK matches the daemon's
+ * registered public key.
+ *
+ * Throws on invalid input (bad URL, bad method, etc.) — never produces
+ * a malformed proof. A failed sign at the daemon side is a hard error,
+ * not a silent fallback.
+ */
+export declare function buildProof(privateJwk: Ed25519PrivateJwk, publicJwk: Ed25519PublicJwk, opts: BuildProofOptions): string;
+export type VerifyFailureReason = 'malformed' | 'bad_alg' | 'bad_typ' | 'bad_jwk' | 'sig_invalid' | 'iat_old' | 'iat_future' | 'htm_mismatch' | 'htu_mismatch' | 'rth_mismatch' | 'ath_mismatch' | 'pin_mismatch';
+export interface VerifySuccess {
+    valid: true;
+    claims: DeviceProofClaims;
+    publicJwk: Ed25519PublicJwk;
+    thumbprint: string;
+}
+export interface VerifyFailure {
+    valid: false;
+    reason: VerifyFailureReason;
+}
+export interface VerifyOptions {
+    /** Expected HTTP method. Compared case-insensitively (proof claim is
+     *  uppercase by construction). */
+    expectedHtm?: string;
+    /** Expected HTTP URI. Normalized before comparison. */
+    expectedHtu?: string;
+    /** Maximum proof age in seconds. Default 60s. */
+    maxAgeSeconds?: number;
+    /** Tolerated negative skew (server clock ahead of daemon). Default 5s. */
+    clockSkewSeconds?: number;
+    /** Refresh-token hash that the proof must commit to. Server side: derive from the body. */
+    expectedRth?: string;
+    /** Access-token hash that the proof must commit to. */
+    expectedAth?: string;
+    /** Public JWK pinned at the server side. When provided, the proof's
+     *  inlined JWK MUST equal this — defends against a stolen valid
+     *  proof signed by a different (e.g., revoked) device. */
+    pinnedPublicJwk?: Ed25519PublicJwk;
+    /** Override the wall clock — testing hook. Defaults to `Date.now()`. */
+    now?: number;
+}
+/**
+ * Verify a device-identity proof. Returns a discriminated union — the
+ * reason is part of the failure shape so the server middleware can emit
+ * structured telemetry without re-parsing.
+ *
+ * Critical: Node's `crypto.verify` returns false on a bad signature
+ * AND throws on a structurally-broken key. Both are surfaced as
+ * `sig_invalid` to keep the failure surface narrow.
+ */
+export declare function verifyProof(jws: string, opts?: VerifyOptions): VerifySuccess | VerifyFailure;

package/dist/esm/deviceKey.js

@@ -0,0 +1,320 @@
+/**
+ * deviceKey.ts — L11 Phase 1: Ed25519 device identity + DPoP-style proofs.
+ *
+ * The load-bearing recommendation in `docs/daemon-auth-cc-deep-comparison-
+ * 2026-04-24.md` §L11. Two-axis identity:
+ *
+ *   user identity  = OAuth refresh token  (server-rotated, scope-pinned, reuse-detected)
+ *   device identity = Ed25519 keypair      (device-generated, server-revocable)
+ *
+ * Every daemon→server request carries a JWS signature over
+ * `{htm, htu, iat, jti, rth?, ath?}` using the device key. Server validates
+ * against the public key registered for this daemon.
+ *
+ * Stolen credentials require BOTH halves:
+ *   - refresh token alone is useless without the device key
+ *   - device key alone is useless without the refresh token
+ *
+ * Why DPoP-shaped (RFC 9449) rather than rolling our own JWS:
+ *   - The htm/htu/iat/jti/ath claim set is well-studied. Server-side
+ *     replay defenses, clock-skew handling, and audit-trail formats all
+ *     have a body of prior art to copy from.
+ *   - Future interop: if we ever expose OverSky as a third-party OAuth
+ *     resource server, DPoP-bearer is the way clients will already
+ *     understand.
+ *
+ * Why we extend with `rth` (refresh-token-hash):
+ *   - RFC 9449 only mints `ath` (access-token-hash). The whole point of
+ *     L11 is to bind the *refresh* token to the device, so the proof
+ *     accompanying a refresh request must commit to the refresh token.
+ *     `rth` is structurally identical to `ath`; the name disambiguates.
+ *
+ * What this module is NOT responsible for:
+ *   - Persistence (lives in `daemon/src/deviceIdentity.ts`).
+ *   - Server-side public-key registration (separate API in a later PR).
+ *   - Wire-up to the daemon's outgoing HTTP path (Phase 2 of L11).
+ */
+import crypto from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Base64url helpers — same shape as `credentialEnvelope.ts` so the two
+// modules are visually consistent in the auth-core codebase.
+// ---------------------------------------------------------------------------
+function b64u(buf) {
+    return buf.toString('base64').replace(/=+$/, '').replace(/\+/g, '-').replace(/\//g, '_');
+}
+function b64uDecode(s) {
+    const padded = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = padded.length % 4;
+    return Buffer.from(pad === 0 ? padded : padded + '='.repeat(4 - pad), 'base64');
+}
+// ---------------------------------------------------------------------------
+// Key generation + canonicalization
+// ---------------------------------------------------------------------------
+/**
+ * Generate a fresh Ed25519 keypair. Uses Node's native bindings —
+ * `crypto.generateKeyPairSync('ed25519')` is available since Node 12 and
+ * is the same primitive `crypto.sign(null, ..., privateKey)` consumes.
+ *
+ * Output is the JWK form (RFC 8037) so callers can serialize directly
+ * without dealing with PKCS#8 or raw byte representations. The private
+ * scalar `d` and public point `x` are 32 bytes each.
+ */
+export function generateDeviceKeyPair() {
+    const { privateKey } = crypto.generateKeyPairSync('ed25519');
+    // `crypto.KeyObject.export({format: 'jwk'})` for an Ed25519 private
+    // key yields {kty, crv, d, x} — both halves in one shot. Saves a
+    // separate call to derive the public form.
+    const jwk = privateKey.export({ format: 'jwk' });
+    if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519') {
+        throw new Error(`generateDeviceKeyPair: unexpected JWK kty/crv (${jwk.kty}/${jwk.crv})`);
+    }
+    const privateJwk = { kty: 'OKP', crv: 'Ed25519', d: jwk.d, x: jwk.x };
+    const publicJwk = { kty: 'OKP', crv: 'Ed25519', x: jwk.x };
+    return {
+        publicJwk,
+        privateJwk,
+        thumbprint: jwkThumbprint(publicJwk),
+    };
+}
+/**
+ * RFC 7638 JWK Thumbprint — SHA-256 of the canonical JSON of the
+ * required members. For an OKP key those are `crv`, `kty`, and `x`,
+ * lexicographically ordered with no whitespace.
+ *
+ * Stable across implementations: a server that derives the thumbprint
+ * the same way always agrees with us. This is the value we use as the
+ * `kid` in JWS headers and as the registered identifier on the server's
+ * `Daemon` table.
+ */
+export function jwkThumbprint(publicJwk) {
+    // Manually constructed — JSON.stringify with object literal does NOT
+    // guarantee key order across Node versions, even though current V8
+    // preserves insertion order. Build the bytes ourselves to defend
+    // against a hypothetical future regression.
+    const canonical = `{"crv":"${publicJwk.crv}","kty":"${publicJwk.kty}","x":"${publicJwk.x}"}`;
+    return b64u(crypto.createHash('sha256').update(canonical, 'utf-8').digest());
+}
+/**
+ * Construct an `Ed25519PublicJwk` from a base64url-encoded 32-byte
+ * public point. Used by the persistence layer when reading a stored
+ * public key; rejects garbage so a corrupted JWK file fails loudly
+ * rather than producing a silently-broken signing key.
+ */
+export function publicJwkFromX(x) {
+    const raw = b64uDecode(x);
+    if (raw.length !== 32) {
+        throw new Error(`publicJwkFromX: expected 32-byte public point, got ${raw.length}`);
+    }
+    return { kty: 'OKP', crv: 'Ed25519', x };
+}
+// ---------------------------------------------------------------------------
+// Token-hash and HTU normalization — RFC 9449 §4.1, §4.2
+// ---------------------------------------------------------------------------
+/**
+ * `ath` / `rth` claim value: SHA-256 of the token ASCII bytes,
+ * base64url-encoded (no padding). Must match exactly on both sides.
+ */
+export function tokenHash(token) {
+    if (typeof token !== 'string' || token.length === 0) {
+        throw new Error('tokenHash: token must be a non-empty string');
+    }
+    return b64u(crypto.createHash('sha256').update(token, 'utf-8').digest());
+}
+/**
+ * Normalize a URL for the `htu` claim per RFC 9449 §4.2:
+ *   - strip query string
+ *   - strip fragment
+ *   - strip userinfo
+ *   - lowercase scheme and host
+ *
+ * The path is left as-is (case-sensitive per RFC 3986). Trailing slash
+ * is preserved — the server compares to its own normalized form so as
+ * long as both sides use the same rule the comparison holds.
+ */
+export function normalizeHtu(url) {
+    const u = new URL(url);
+    u.search = '';
+    u.hash = '';
+    u.username = '';
+    u.password = '';
+    return u.toString();
+}
+/**
+ * Build a JWS Compact Serialization device-identity proof.
+ *
+ * Header includes the public JWK inline (RFC 9449 pattern) so the
+ * server can verify the signature without prior key lookup, then
+ * additionally check that the inlined JWK matches the daemon's
+ * registered public key.
+ *
+ * Throws on invalid input (bad URL, bad method, etc.) — never produces
+ * a malformed proof. A failed sign at the daemon side is a hard error,
+ * not a silent fallback.
+ */
+export function buildProof(privateJwk, publicJwk, opts) {
+    if (typeof opts.method !== 'string' || opts.method.length === 0) {
+        throw new Error('buildProof: method must be a non-empty string');
+    }
+    if (typeof opts.url !== 'string' || opts.url.length === 0) {
+        throw new Error('buildProof: url must be a non-empty string');
+    }
+    if (publicJwk.x !== privateJwk.x) {
+        // Defensive — public and private must come from the same keypair.
+        // A mismatch indicates a corrupted in-memory state.
+        throw new Error('buildProof: public/private JWK x mismatch (corrupted keypair)');
+    }
+    const claims = {
+        htm: opts.method.toUpperCase(),
+        htu: normalizeHtu(opts.url),
+        iat: opts.iat ?? Math.floor(Date.now() / 1000),
+        jti: opts.jti ?? b64u(crypto.randomBytes(16)),
+    };
+    if (opts.refreshToken !== undefined)
+        claims.rth = tokenHash(opts.refreshToken);
+    if (opts.accessToken !== undefined)
+        claims.ath = tokenHash(opts.accessToken);
+    const header = {
+        alg: 'EdDSA',
+        typ: 'oversky-dpop+jwt',
+        jwk: publicJwk,
+    };
+    const headerB64 = b64u(Buffer.from(JSON.stringify(header), 'utf-8'));
+    const payloadB64 = b64u(Buffer.from(JSON.stringify(claims), 'utf-8'));
+    const signingInput = `${headerB64}.${payloadB64}`;
+    // Cast to crypto's `JsonWebKey` shape — that type requires an index
+    // signature for arbitrary string keys; our narrow OKP shape doesn't
+    // declare one because the strict shape is more useful at our API
+    // boundary. Cast through `unknown` to silence the structural mismatch
+    // without losing the rest of the type safety on this surface.
+    const privateKey = crypto.createPrivateKey({
+        format: 'jwk',
+        key: privateJwk,
+    });
+    // EdDSA over Ed25519 — Node's crypto.sign expects `null` as the
+    // digest algorithm because Ed25519 hashes the message internally.
+    const signature = crypto.sign(null, Buffer.from(signingInput, 'utf-8'), privateKey);
+    return `${signingInput}.${b64u(signature)}`;
+}
+/**
+ * Verify a device-identity proof. Returns a discriminated union — the
+ * reason is part of the failure shape so the server middleware can emit
+ * structured telemetry without re-parsing.
+ *
+ * Critical: Node's `crypto.verify` returns false on a bad signature
+ * AND throws on a structurally-broken key. Both are surfaced as
+ * `sig_invalid` to keep the failure surface narrow.
+ */
+export function verifyProof(jws, opts = {}) {
+    if (typeof jws !== 'string' || jws.length === 0) {
+        return { valid: false, reason: 'malformed' };
+    }
+    const parts = jws.split('.');
+    if (parts.length !== 3) {
+        return { valid: false, reason: 'malformed' };
+    }
+    const [headerB64, payloadB64, sigB64] = parts;
+    let header;
+    let claims;
+    try {
+        header = JSON.parse(b64uDecode(headerB64).toString('utf-8'));
+        claims = JSON.parse(b64uDecode(payloadB64).toString('utf-8'));
+    }
+    catch {
+        return { valid: false, reason: 'malformed' };
+    }
+    if (!header || typeof header !== 'object' || header.alg !== 'EdDSA') {
+        return { valid: false, reason: 'bad_alg' };
+    }
+    if (header.typ !== 'oversky-dpop+jwt') {
+        return { valid: false, reason: 'bad_typ' };
+    }
+    const headerJwk = header.jwk;
+    if (!headerJwk ||
+        typeof headerJwk !== 'object' ||
+        headerJwk.kty !== 'OKP' ||
+        headerJwk.crv !== 'Ed25519' ||
+        typeof headerJwk.x !== 'string') {
+        return { valid: false, reason: 'bad_jwk' };
+    }
+    const publicJwk = {
+        kty: 'OKP',
+        crv: 'Ed25519',
+        x: headerJwk.x,
+    };
+    // Validate the public point length — defends against an attacker who
+    // smuggles a non-32-byte `x` to confuse downstream consumers.
+    let publicKeyObj;
+    try {
+        const raw = b64uDecode(publicJwk.x);
+        if (raw.length !== 32) {
+            return { valid: false, reason: 'bad_jwk' };
+        }
+        publicKeyObj = crypto.createPublicKey({
+            format: 'jwk',
+            key: publicJwk,
+        });
+    }
+    catch {
+        return { valid: false, reason: 'bad_jwk' };
+    }
+    if (opts.pinnedPublicJwk && opts.pinnedPublicJwk.x !== publicJwk.x) {
+        return { valid: false, reason: 'pin_mismatch' };
+    }
+    // Verify the signature itself before validating claims — a bad
+    // signature should always be the reported failure (more important
+    // signal than a stale iat).
+    const signingInput = Buffer.from(`${headerB64}.${payloadB64}`, 'utf-8');
+    let signature;
+    try {
+        signature = b64uDecode(sigB64);
+    }
+    catch {
+        return { valid: false, reason: 'malformed' };
+    }
+    let sigOk;
+    try {
+        sigOk = crypto.verify(null, signingInput, publicKeyObj, signature);
+    }
+    catch {
+        sigOk = false;
+    }
+    if (!sigOk) {
+        return { valid: false, reason: 'sig_invalid' };
+    }
+    // Claim-level checks.
+    const now = Math.floor((opts.now ?? Date.now()) / 1000);
+    const maxAge = opts.maxAgeSeconds ?? 60;
+    const skew = opts.clockSkewSeconds ?? 5;
+    if (typeof claims.iat !== 'number' || !Number.isFinite(claims.iat)) {
+        return { valid: false, reason: 'malformed' };
+    }
+    if (claims.iat > now + skew) {
+        return { valid: false, reason: 'iat_future' };
+    }
+    if (claims.iat < now - maxAge) {
+        return { valid: false, reason: 'iat_old' };
+    }
+    if (typeof claims.htm !== 'string' ||
+        typeof claims.htu !== 'string' ||
+        typeof claims.jti !== 'string') {
+        return { valid: false, reason: 'malformed' };
+    }
+    if (opts.expectedHtm && claims.htm !== opts.expectedHtm.toUpperCase()) {
+        return { valid: false, reason: 'htm_mismatch' };
+    }
+    if (opts.expectedHtu && claims.htu !== normalizeHtu(opts.expectedHtu)) {
+        return { valid: false, reason: 'htu_mismatch' };
+    }
+    if (opts.expectedRth !== undefined && claims.rth !== opts.expectedRth) {
+        return { valid: false, reason: 'rth_mismatch' };
+    }
+    if (opts.expectedAth !== undefined && claims.ath !== opts.expectedAth) {
+        return { valid: false, reason: 'ath_mismatch' };
+    }
+    return {
+        valid: true,
+        claims,
+        publicJwk,
+        thumbprint: jwkThumbprint(publicJwk),
+    };
+}

package/dist/esm/fdToken.d.ts

@@ -0,0 +1,17 @@
+export interface FdAuthPayload {
+    accessToken: string;
+    accessExpiresAt?: number;
+    refreshToken?: string;
+    refreshExpiresAt?: number;
+}
+/** @internal test-only — replace the fd reader. Pass null to restore. */
+export declare function __setFdReaderForTest(fn: ((fd: number) => string | Promise<string>) | null): void;
+/**
+ * Attempt a one-shot read of the handoff fd. Returns the parsed payload on
+ * success, or null on any failure (missing env var, bad fd, bad JSON, etc.).
+ *
+ * Side effect: on the first successful read the env var is scrubbed so a
+ * later caller that misses every in-process cache doesn't retry the now-
+ * closed fd.
+ */
+export declare function readAuthFromFd(): Promise<FdAuthPayload | null>;