@planetlogin/core 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @planetlogin/core
+
+The framework-agnostic **auth core** of PlanetLogin: the flows (password, magic link,
+OAuth/OIDC, passkeys, TOTP), JWT/JWKS, all-terrain password verification, the
+downstream contract client, and the pluggable session store.
+
+No HTTP, no framework. Each **flavor** adds only its runtime's HTTP binding and calls
+into this package — so the auth logic lives once and every flavor stays in lockstep
+with the [SPEC](../planetpass/SPEC.md). It also owns the **test suite (31 tests, typecheck clean)** — the logic is validated
+here, not in any flavor. Verified: the vanilla flavor consumes this and passes the
+conformance suite 9/9; the SvelteKit flavor builds green over it.
+
+```ts
+import { passwordLogin, signSession, verifyPassword, downstreamFromEnv } from '@planetlogin/core';
+```
+
+Pure dependencies only (jose, hash-wasm, bcryptjs, @simplewebauthn/server, otpauth) —
+no crypto is hand-rolled. Runs under tsx today; ships as compiled JS for publishing.
+
+## Build
+
+```bash
+npm run build   # tsup → dist/index.js (ESM) + dist/index.d.ts
+npm test        # 31 tests   ·   npm run typecheck
+```
+
+Flavors consume the built `dist/` (the `exports`/`types`/`main` all point there), so
+they never transpile core source. `prepublishOnly` rebuilds before npm publish.

package/dist/index.d.ts

@@ -0,0 +1,493 @@
+import * as jose from 'jose';
+import { JWK } from 'jose';
+import * as _simplewebauthn_server from '@simplewebauthn/server';
+
+interface Locale {
+    language?: string;
+    timezone?: string;
+    country?: string;
+}
+interface SessionClaims {
+    sub: string;
+    email?: string;
+    name?: string;
+    locale?: Locale;
+}
+/** Public JWK Set served at GET /auth/.well-known/jwks.json. */
+declare function jwks(): Promise<{
+    keys: JWK[];
+}>;
+declare function signSession(claims: SessionClaims, opts?: {
+    issuer?: string;
+    audience?: string;
+    ttlSeconds?: number;
+}): Promise<string>;
+/** Verify a session token against our own JWKS (what a downstream service does). */
+declare function verifySession(token: string): Promise<jose.JWTPayload>;
+declare function signMagicToken(identifier: string, ttlSeconds?: number): Promise<string>;
+/** Returns {identifier, jti} if the token is a valid, unexpired magic token, else null. */
+declare function verifyMagicToken(token: string): Promise<{
+    identifier: string;
+    jti: string;
+} | null>;
+
+interface DownstreamUser {
+    id: string;
+    email?: string;
+    name?: string;
+    passwordHash?: string;
+    locale?: Locale;
+    totpEnabled?: boolean;
+}
+declare class Downstream {
+    private baseUrl;
+    private secret;
+    private timeoutMs;
+    private fetchImpl;
+    constructor(baseUrl: string, secret: string, timeoutMs?: number, fetchImpl?: typeof fetch);
+    private call;
+    findUser(identifier: string): Promise<DownstreamUser | null>;
+    upsertUser(data: {
+        provider: string;
+        providerUserId?: string;
+        email?: string;
+        name?: string;
+        profile?: unknown;
+    }): Promise<DownstreamUser | null>;
+    /** Ask the integrator to deliver a magic link (it sends the email/SMS). */
+    deliverMagic(data: {
+        identifier: string;
+        link: string;
+        locale?: Locale;
+    }): Promise<unknown>;
+    /** Passkeys (spec §4): the integrator stores WebAuthn credentials. */
+    passkeysFind(query: {
+        userId?: string;
+        credentialId?: string;
+    }): Promise<{
+        userId: string;
+        credentials: any[];
+    } | null>;
+    passkeysSave(data: {
+        userId: string;
+        credential: any;
+    }): Promise<unknown>;
+    /** TOTP (2FA): the integrator stores the per-user secret + enabled flag. */
+    totpGet(query: {
+        userId: string;
+    }): Promise<{
+        secret: string;
+        enabled: boolean;
+    } | null>;
+    totpSave(data: {
+        userId: string;
+        secret: string;
+        enabled: boolean;
+    }): Promise<unknown>;
+}
+
+interface PlanetLoginConfig {
+    spec: 1;
+    brand: {
+        name: string;
+        logoUrl?: string;
+        accent?: string;
+        background?: string;
+    };
+    providers: {
+        password?: {
+            enabled?: boolean;
+            allowRegister?: boolean;
+        };
+        oauth?: Array<{
+            id: string;
+            label?: string;
+            clientIdEnv?: string;
+        }>;
+        magicLink?: {
+            enabled?: boolean;
+            ttlSeconds?: number;
+        };
+        passkeys?: {
+            enabled?: boolean;
+        };
+        totp?: {
+            enabled?: boolean;
+        };
+        saml?: {
+            enabled?: boolean;
+            idpMetadataUrl?: string;
+        };
+    };
+    copy?: Record<string, Record<string, string>>;
+    layout?: {
+        globePosition?: 'left' | 'right' | 'full';
+        showSearch?: boolean;
+        autoSpin?: boolean;
+    };
+    token?: {
+        issuer?: string;
+        audience?: string;
+        ttlSeconds?: number;
+        algorithm?: 'EdDSA' | 'RS256' | 'ES256' | 'HS256';
+    };
+    session?: {
+        store?: 'none' | 'memory' | 'redis' | 'sqlite' | 'downstream';
+    };
+}
+declare function loadConfig(): PlanetLoginConfig;
+/** The public subset served at GET /auth/config (no secrets). */
+declare function publicConfig(c?: PlanetLoginConfig): {
+    spec: 1;
+    brand: {
+        name: string;
+        logoUrl?: string;
+        accent?: string;
+        background?: string;
+    };
+    providers: {
+        password?: {
+            enabled?: boolean;
+            allowRegister?: boolean;
+        };
+        oauth?: Array<{
+            id: string;
+            label?: string;
+            clientIdEnv?: string;
+        }>;
+        magicLink?: {
+            enabled?: boolean;
+            ttlSeconds?: number;
+        };
+        passkeys?: {
+            enabled?: boolean;
+        };
+        totp?: {
+            enabled?: boolean;
+        };
+        saml?: {
+            enabled?: boolean;
+            idpMetadataUrl?: string;
+        };
+    };
+    copy: Record<string, Record<string, string>>;
+    layout: {
+        globePosition?: "left" | "right" | "full";
+        showSearch?: boolean;
+        autoSpin?: boolean;
+    };
+};
+declare function downstreamFromEnv(): Downstream;
+
+declare function hashPassword(password: string): Promise<string>;
+/**
+ * Verify a plaintext password against a stored hash of ANY supported format.
+ * Detection is by the encoded-hash prefix. Never throws → returns false on any
+ * parse/verify failure or unknown/unsafe format (fail closed).
+ */
+declare function verifyPassword(password: string, stored: string): Promise<boolean>;
+
+interface SessionStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Atomically claim a key once: true if newly claimed, false if already present. */
+    claimOnce(key: string, ttlSeconds: number): Promise<boolean>;
+}
+/** No store: stateless. claimOnce always allows (single-use not enforced → TTL only). */
+declare class NoneStore implements SessionStore {
+    get(): Promise<null>;
+    set(): Promise<void>;
+    delete(): Promise<void>;
+    claimOnce(): Promise<boolean>;
+}
+declare class MemoryStore implements SessionStore {
+    private m;
+    private alive;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    claimOnce(key: string, ttlSeconds: number): Promise<boolean>;
+}
+type StoreKind = 'none' | 'memory' | 'redis' | 'sqlite' | 'downstream';
+/** Build the store from config. Only none+memory ship in this flavor; the rest
+ *  are declared in the spec and added per deployment need. */
+declare function getStore(kind?: StoreKind): SessionStore;
+declare const _stores: {
+    NoneStore: typeof NoneStore;
+    MemoryStore: typeof MemoryStore;
+};
+
+interface ProviderConfig {
+    authorizeUrl: string;
+    tokenUrl: string;
+    userinfoUrl: string;
+    scopes: string[];
+    mapProfile: (raw: any) => {
+        providerUserId: string;
+        email?: string;
+        name?: string;
+    };
+}
+declare function pkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+/** Resolve a provider config. Endpoints are overridable per provider via env
+ *  (PLANETLOGIN_OAUTH_<ID>_{AUTHORIZE,TOKEN,USERINFO}_URL). Unknown ids become a
+ *  generic OIDC-shaped provider built entirely from those env vars. */
+declare function getProvider(id: string): ProviderConfig;
+declare function buildAuthUrl(p: ProviderConfig, a: {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    challenge: string;
+}): string;
+/** /start helper: PKCE pair + state + the authorization URL. */
+declare function oauthStart(p: ProviderConfig, a: {
+    clientId: string;
+    redirectUri: string;
+}): {
+    url: string;
+    state: string;
+    codeVerifier: string;
+};
+declare function exchangeCode(p: ProviderConfig, a: {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+}): Promise<string>;
+declare function fetchProfile(p: ProviderConfig, accessToken: string): Promise<{
+    providerUserId: string;
+    email?: string;
+    name?: string;
+}>;
+
+interface OAuthStateData {
+    provider: string;
+    state: string;
+    codeVerifier: string;
+    redirectTo: string;
+}
+/** Generic short-lived encrypted (JWE A256GCM) cookie payload — used to keep
+ *  OAuth state and WebAuthn challenges across a redirect/ceremony, statelessly. */
+declare function sealEnc(data: unknown, ttlSeconds?: number): Promise<string>;
+declare function openEnc<T = any>(token: string): Promise<T | null>;
+declare const sealOAuthState: (d: OAuthStateData, ttl?: number) => Promise<string>;
+declare const openOAuthState: (t: string) => Promise<OAuthStateData | null>;
+
+interface StoredCredential {
+    id: string;
+    publicKey: string;
+    counter: number;
+    transports?: string[];
+}
+declare function registrationOptions(a: {
+    rpID: string;
+    rpName: string;
+    userId: string;
+    userName: string;
+    existing?: StoredCredential[];
+}): Promise<_simplewebauthn_server.PublicKeyCredentialCreationOptionsJSON>;
+declare function authenticationOptions(a: {
+    rpID: string;
+    allow?: StoredCredential[];
+}): Promise<_simplewebauthn_server.PublicKeyCredentialRequestOptionsJSON>;
+declare function verifyRegistration(a: {
+    response: any;
+    expectedChallenge: string;
+    origin: string;
+    rpID: string;
+}): Promise<{
+    verified: boolean;
+    credential?: StoredCredential;
+}>;
+declare function verifyAuthentication(a: {
+    response: any;
+    expectedChallenge: string;
+    origin: string;
+    rpID: string;
+    credential: StoredCredential;
+}): Promise<{
+    verified: boolean;
+    newCounter?: number;
+}>;
+
+declare function newTotpSecret(): string;
+declare function totpKeyUri(secretB32: string, label: string, issuer?: string): string;
+/** Verify a 6-digit code (±1 step window for clock skew). Never throws. */
+declare function verifyTotp(secretB32: string, code: string): boolean;
+
+interface PasswordLoginDeps {
+    downstream: Downstream;
+    verifyPassword: (password: string, hash: string) => Promise<boolean>;
+    signSession: (claims: SessionClaims) => Promise<string>;
+}
+interface PasswordLoginInput {
+    identifier: string;
+    password: string;
+    locale?: Locale;
+}
+type PasswordLoginResult = {
+    ok: true;
+    token: string;
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+} | {
+    ok: 'mfa';
+    userId: string;
+} | {
+    ok: false;
+    code: 'invalid_credentials' | 'downstream_unavailable';
+};
+declare function passwordLogin(deps: PasswordLoginDeps, input: PasswordLoginInput): Promise<PasswordLoginResult>;
+
+interface MagicRequestDeps {
+    downstream: Downstream;
+    signMagicToken: (identifier: string) => Promise<string>;
+}
+interface MagicVerifyDeps {
+    downstream: Downstream;
+    verifyMagicToken: (token: string) => Promise<{
+        identifier: string;
+        jti: string;
+    } | null>;
+    signSession: (claims: SessionClaims) => Promise<string>;
+    store: SessionStore;
+}
+/** Always resolves `{ accepted: true }` (the route returns 202) — no enumeration. */
+declare function requestMagicLink(deps: MagicRequestDeps, input: {
+    identifier: string;
+    baseUrl: string;
+    locale?: Locale;
+}): Promise<{
+    accepted: true;
+}>;
+type MagicVerifyResult = {
+    ok: true;
+    token: string;
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+} | {
+    ok: false;
+    code: 'invalid_token';
+};
+declare function verifyMagicLink(deps: MagicVerifyDeps, input: {
+    token: string;
+    locale?: Locale;
+}): Promise<MagicVerifyResult>;
+
+interface OAuthLoginDeps {
+    downstream: Downstream;
+    signSession: (claims: SessionClaims) => Promise<string>;
+}
+interface OAuthLoginInput {
+    provider: string;
+    providerCfg: ProviderConfig;
+    code: string;
+    codeVerifier: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    locale?: Locale;
+}
+type OAuthLoginResult = {
+    ok: true;
+    token: string;
+    user: {
+        id: string;
+        email?: string;
+        name?: string;
+    };
+} | {
+    ok: false;
+    code: 'provider_error';
+};
+declare function oauthCallback(deps: OAuthLoginDeps, input: OAuthLoginInput): Promise<OAuthLoginResult>;
+
+interface RegisterVerifyDeps {
+    downstream: Downstream;
+    verifyRegistration: (a: {
+        response: any;
+        expectedChallenge: string;
+        origin: string;
+        rpID: string;
+    }) => Promise<{
+        verified: boolean;
+        credential?: StoredCredential;
+    }>;
+}
+interface AuthVerifyDeps {
+    downstream: Downstream;
+    verifyAuthentication: (a: {
+        response: any;
+        expectedChallenge: string;
+        origin: string;
+        rpID: string;
+        credential: StoredCredential;
+    }) => Promise<{
+        verified: boolean;
+        newCounter?: number;
+    }>;
+    signSession: (claims: SessionClaims) => Promise<string>;
+}
+type RegisterResult = {
+    ok: true;
+} | {
+    ok: false;
+    code: 'invalid_credentials';
+};
+type AuthResult = {
+    ok: true;
+    token: string;
+    user: {
+        id: string;
+    };
+} | {
+    ok: false;
+    code: 'invalid_credentials';
+};
+declare function passkeyRegisterVerify(deps: RegisterVerifyDeps, input: {
+    response: any;
+    expectedChallenge: string;
+    userId: string;
+    origin: string;
+    rpID: string;
+}): Promise<RegisterResult>;
+declare function passkeyAuthVerify(deps: AuthVerifyDeps, input: {
+    response: any;
+    expectedChallenge: string;
+    origin: string;
+    rpID: string;
+    locale?: Locale;
+}): Promise<AuthResult>;
+
+interface TotpDeps {
+    downstream: Downstream;
+}
+declare function totpEnroll(deps: TotpDeps, input: {
+    userId: string;
+    label: string;
+    issuer?: string;
+}): Promise<{
+    secret: string;
+    uri: string;
+}>;
+/** Verify a code. On first success for a not-yet-enabled secret, enable it
+ *  (confirms enrollment). Returns ok=false on any failure. */
+declare function totpVerify(deps: TotpDeps, input: {
+    userId: string;
+    code: string;
+}): Promise<{
+    ok: boolean;
+}>;
+
+export { type AuthResult, type AuthVerifyDeps, Downstream, type DownstreamUser, type Locale, type MagicRequestDeps, type MagicVerifyDeps, type MagicVerifyResult, type OAuthLoginDeps, type OAuthLoginInput, type OAuthLoginResult, type OAuthStateData, type PasswordLoginDeps, type PasswordLoginInput, type PasswordLoginResult, type PlanetLoginConfig, type ProviderConfig, type RegisterResult, type RegisterVerifyDeps, type SessionClaims, type SessionStore, type StoreKind, type StoredCredential, type TotpDeps, _stores, authenticationOptions, buildAuthUrl, downstreamFromEnv, exchangeCode, fetchProfile, getProvider, getStore, hashPassword, jwks, loadConfig, newTotpSecret, oauthCallback, oauthStart, openEnc, openOAuthState, passkeyAuthVerify, passkeyRegisterVerify, passwordLogin, pkcePair, publicConfig, registrationOptions, requestMagicLink, sealEnc, sealOAuthState, signMagicToken, signSession, totpEnroll, totpKeyUri, totpVerify, verifyAuthentication, verifyMagicLink, verifyMagicToken, verifyPassword, verifyRegistration, verifySession, verifyTotp };

package/dist/index.js

@@ -0,0 +1,594 @@
+// src/config.ts
+import { readFileSync } from "fs";
+
+// src/downstream.ts
+var Downstream = class {
+  constructor(baseUrl, secret, timeoutMs = Number(process.env.PLANETLOGIN_DOWNSTREAM_TIMEOUT_MS) || 5e3, fetchImpl = fetch) {
+    this.baseUrl = baseUrl;
+    this.secret = secret;
+    this.timeoutMs = timeoutMs;
+    this.fetchImpl = fetchImpl;
+  }
+  baseUrl;
+  secret;
+  timeoutMs;
+  fetchImpl;
+  async call(path, body) {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this.fetchImpl(this.baseUrl.replace(/\/$/, "") + path, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${this.secret}` },
+        body: JSON.stringify(body),
+        signal: ctrl.signal
+      });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`downstream ${path} \u2192 ${res.status}`);
+      const text = await res.text();
+      return text ? JSON.parse(text) : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  findUser(identifier) {
+    return this.call("/users/find", { identifier });
+  }
+  upsertUser(data) {
+    return this.call("/users/upsert", data);
+  }
+  /** Ask the integrator to deliver a magic link (it sends the email/SMS). */
+  deliverMagic(data) {
+    return this.call("/magic/deliver", data);
+  }
+  /** Passkeys (spec §4): the integrator stores WebAuthn credentials. */
+  passkeysFind(query) {
+    return this.call("/passkeys/find", query);
+  }
+  passkeysSave(data) {
+    return this.call("/passkeys/save", data);
+  }
+  /** TOTP (2FA): the integrator stores the per-user secret + enabled flag. */
+  totpGet(query) {
+    return this.call("/totp/find", query);
+  }
+  totpSave(data) {
+    return this.call("/totp/save", data);
+  }
+};
+
+// src/config.ts
+var cfg = null;
+function loadConfig() {
+  if (cfg) return cfg;
+  const raw = process.env.PLANETLOGIN_CONFIG;
+  if (!raw) throw new Error("PLANETLOGIN_CONFIG is required (path or inline JSON)");
+  const text = raw.trim().startsWith("{") ? raw : readFileSync(raw, "utf8");
+  const parsed = JSON.parse(text);
+  if (parsed.spec !== 1) throw new Error(`Unsupported config spec: ${parsed.spec}`);
+  if (!parsed.brand?.name) throw new Error("config.brand.name is required");
+  cfg = parsed;
+  return cfg;
+}
+function publicConfig(c = loadConfig()) {
+  return { spec: c.spec, brand: c.brand, providers: c.providers, copy: c.copy ?? {}, layout: c.layout ?? {} };
+}
+function downstreamFromEnv() {
+  const url = process.env.PLANETLOGIN_DOWNSTREAM_URL;
+  const secret = process.env.PLANETLOGIN_DOWNSTREAM_SECRET;
+  if (!url || !secret) throw new Error("PLANETLOGIN_DOWNSTREAM_URL and _SECRET are required");
+  return new Downstream(url, secret);
+}
+
+// src/jwt.ts
+import {
+  SignJWT,
+  jwtVerify,
+  exportJWK,
+  generateKeyPair,
+  importPKCS8,
+  createLocalJWKSet
+} from "jose";
+var cache = null;
+async function getKeys() {
+  if (cache) return cache;
+  let priv;
+  const pem = process.env.PLANETLOGIN_JWT_PRIVATE_KEY_PEM;
+  if (pem) {
+    priv = await importPKCS8(pem, "EdDSA");
+  } else {
+    priv = (await generateKeyPair("EdDSA", { extractable: true })).privateKey;
+  }
+  const full = await exportJWK(priv);
+  const { d, ...pub } = full;
+  const kid = process.env.PLANETLOGIN_JWT_KID || "dev";
+  cache = { priv, pubJwk: { ...pub, kid, use: "sig", alg: "EdDSA" }, kid };
+  return cache;
+}
+async function jwks() {
+  const k = await getKeys();
+  return { keys: [k.pubJwk] };
+}
+async function signSession(claims, opts = {}) {
+  const k = await getKeys();
+  return new SignJWT({ email: claims.email, name: claims.name, locale: claims.locale }).setProtectedHeader({ alg: "EdDSA", kid: k.kid }).setSubject(claims.sub).setIssuedAt().setExpirationTime(`${opts.ttlSeconds ?? 3600}s`).setIssuer(opts.issuer ?? "planetlogin").setAudience(opts.audience ?? "planetlogin").sign(k.priv);
+}
+async function verifySession(token) {
+  const set = await jwks();
+  const keySet = createLocalJWKSet(set);
+  const { payload } = await jwtVerify(token, keySet, { issuer: "planetlogin", audience: "planetlogin" });
+  return payload;
+}
+async function signMagicToken(identifier, ttlSeconds = 900) {
+  const k = await getKeys();
+  return new SignJWT({ purpose: "magic" }).setProtectedHeader({ alg: "EdDSA", kid: k.kid }).setSubject(identifier).setJti(crypto.randomUUID()).setIssuedAt().setExpirationTime(`${ttlSeconds}s`).setIssuer("planetlogin").setAudience("planetlogin:magic").sign(k.priv);
+}
+async function verifyMagicToken(token) {
+  try {
+    const set = await jwks();
+    const { payload } = await jwtVerify(token, createLocalJWKSet(set), {
+      issuer: "planetlogin",
+      audience: "planetlogin:magic"
+    });
+    if (payload.purpose !== "magic" || !payload.sub || !payload.jti) return null;
+    return { identifier: payload.sub, jti: payload.jti };
+  } catch {
+    return null;
+  }
+}
+
+// src/password.ts
+import { argon2id, argon2Verify } from "hash-wasm";
+import bcrypt from "bcryptjs";
+import { scrypt as nodeScrypt, pbkdf2 as nodePbkdf2, timingSafeEqual } from "crypto";
+import { promisify } from "util";
+var scryptAsync = promisify(nodeScrypt);
+var pbkdf2Async = promisify(nodePbkdf2);
+var PARAMS = { parallelism: 1, iterations: 2, memorySize: 19456, hashLength: 32 };
+async function hashPassword(password) {
+  const salt = crypto.getRandomValues(new Uint8Array(16));
+  return argon2id({ password, salt, ...PARAMS, outputType: "encoded" });
+}
+var safeEq = (a, b) => a.length === b.length && timingSafeEqual(a, b);
+async function verifyPassword(password, stored) {
+  try {
+    if (!stored) return false;
+    if (stored.startsWith("$argon2")) {
+      return await argon2Verify({ password, hash: stored });
+    }
+    if (/^\$2[aby]\$/.test(stored)) {
+      return await bcrypt.compare(password, stored);
+    }
+    if (stored.startsWith("$scrypt$")) {
+      const [, , params, saltB64, hashB64] = stored.split("$");
+      const p = Object.fromEntries(params.split(",").map((kv) => kv.split("=")));
+      const salt = Buffer.from(saltB64, "base64");
+      const expected = Buffer.from(hashB64, "base64");
+      const N = p.ln ? 2 ** Number(p.ln) : Number(p.N ?? 16384);
+      const derived = await scryptAsync(password, salt, expected.length, { N, r: Number(p.r ?? 8), p: Number(p.p ?? 1), maxmem: 256 * N * Number(p.r ?? 8) });
+      return safeEq(derived, expected);
+    }
+    let m = stored.match(/^pbkdf2_(sha\d+)\$(\d+)\$([^$]+)\$(.+)$/);
+    if (m) {
+      const [, algo, iter, salt, hashB64] = m;
+      const expected = Buffer.from(hashB64, "base64");
+      const derived = await pbkdf2Async(password, Buffer.from(salt, "utf8"), Number(iter), expected.length, algo.replace("sha", "sha"));
+      return safeEq(derived, expected);
+    }
+    m = stored.match(/^\$pbkdf2-(sha\d+)\$(\d+)\$([^$]+)\$(.+)$/);
+    if (m) {
+      const [, algo, iter, saltB64, hashB64] = m;
+      const salt = Buffer.from(saltB64.replace(/\./g, "+"), "base64");
+      const expected = Buffer.from(hashB64.replace(/\./g, "+"), "base64");
+      const derived = await pbkdf2Async(password, salt, Number(iter), expected.length, algo);
+      return safeEq(derived, expected);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// src/store.ts
+var NoneStore = class {
+  async get() {
+    return null;
+  }
+  async set() {
+  }
+  async delete() {
+  }
+  async claimOnce() {
+    return true;
+  }
+};
+var MemoryStore = class {
+  m = /* @__PURE__ */ new Map();
+  alive(key) {
+    const e = this.m.get(key);
+    if (!e) return void 0;
+    if (e.exp <= Date.now()) {
+      this.m.delete(key);
+      return void 0;
+    }
+    return e;
+  }
+  async get(key) {
+    return this.alive(key)?.v ?? null;
+  }
+  async set(key, value, ttlSeconds) {
+    this.m.set(key, { v: value, exp: Date.now() + ttlSeconds * 1e3 });
+  }
+  async delete(key) {
+    this.m.delete(key);
+  }
+  async claimOnce(key, ttlSeconds) {
+    if (this.alive(key)) return false;
+    await this.set(key, "1", ttlSeconds);
+    return true;
+  }
+};
+var cached = null;
+function getStore(kind = process.env.PLANETLOGIN_SESSION_STORE || "none") {
+  if (cached) return cached;
+  switch (kind) {
+    case "memory":
+      cached = new MemoryStore();
+      break;
+    case "none":
+      cached = new NoneStore();
+      break;
+    default:
+      throw new Error(`session.store "${kind}" not implemented in this flavor (use none|memory)`);
+  }
+  return cached;
+}
+var _stores = { NoneStore, MemoryStore };
+
+// src/oauth.ts
+import { createHash, randomBytes } from "crypto";
+var b64url = (b) => b.toString("base64url");
+function pkcePair() {
+  const verifier = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+var REGISTRY = {
+  google: {
+    authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+    tokenUrl: "https://oauth2.googleapis.com/token",
+    userinfoUrl: "https://openidconnect.googleapis.com/v1/userinfo",
+    scopes: ["openid", "email", "profile"],
+    mapProfile: (r) => ({ providerUserId: r.sub, email: r.email, name: r.name })
+  },
+  github: {
+    authorizeUrl: "https://github.com/login/oauth/authorize",
+    tokenUrl: "https://github.com/login/oauth/access_token",
+    userinfoUrl: "https://api.github.com/user",
+    scopes: ["read:user", "user:email"],
+    mapProfile: (r) => ({ providerUserId: String(r.id), email: r.email, name: r.name || r.login })
+  }
+};
+function getProvider(id) {
+  const env = (s) => process.env[`PLANETLOGIN_OAUTH_${id.toUpperCase()}_${s}`];
+  const base = REGISTRY[id] ?? {
+    authorizeUrl: env("AUTHORIZE_URL") || "",
+    tokenUrl: env("TOKEN_URL") || "",
+    userinfoUrl: env("USERINFO_URL") || "",
+    scopes: (env("SCOPES") || "openid email profile").split(" "),
+    mapProfile: (r) => ({ providerUserId: r.sub ?? String(r.id), email: r.email, name: r.name })
+  };
+  return {
+    ...base,
+    authorizeUrl: env("AUTHORIZE_URL") || base.authorizeUrl,
+    tokenUrl: env("TOKEN_URL") || base.tokenUrl,
+    userinfoUrl: env("USERINFO_URL") || base.userinfoUrl
+  };
+}
+function buildAuthUrl(p, a) {
+  const u = new URL(p.authorizeUrl);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("client_id", a.clientId);
+  u.searchParams.set("redirect_uri", a.redirectUri);
+  u.searchParams.set("scope", p.scopes.join(" "));
+  u.searchParams.set("state", a.state);
+  u.searchParams.set("code_challenge", a.challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  return u.toString();
+}
+function oauthStart(p, a) {
+  const { verifier, challenge } = pkcePair();
+  const state = b64url(randomBytes(16));
+  return { url: buildAuthUrl(p, { ...a, state, challenge }), state, codeVerifier: verifier };
+}
+async function exchangeCode(p, a) {
+  const res = await fetch(p.tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code: a.code,
+      redirect_uri: a.redirectUri,
+      client_id: a.clientId,
+      client_secret: a.clientSecret,
+      code_verifier: a.codeVerifier
+    })
+  });
+  if (!res.ok) throw new Error(`token exchange \u2192 ${res.status}`);
+  const tok = await res.json();
+  if (!tok.access_token) throw new Error("no access_token");
+  return tok.access_token;
+}
+async function fetchProfile(p, accessToken) {
+  const res = await fetch(p.userinfoUrl, {
+    headers: { authorization: `Bearer ${accessToken}`, accept: "application/json", "user-agent": "planetlogin" }
+  });
+  if (!res.ok) throw new Error(`userinfo \u2192 ${res.status}`);
+  return p.mapProfile(await res.json());
+}
+
+// src/oauthState.ts
+import { EncryptJWT, jwtDecrypt, base64url } from "jose";
+var stateKey = null;
+function getStateKey() {
+  if (stateKey) return stateKey;
+  const env = process.env.PLANETLOGIN_STATE_KEY;
+  stateKey = env ? base64url.decode(env) : crypto.getRandomValues(new Uint8Array(32));
+  if (stateKey.length !== 32) throw new Error("PLANETLOGIN_STATE_KEY must decode to 32 bytes");
+  return stateKey;
+}
+async function sealEnc(data, ttlSeconds = 600) {
+  return new EncryptJWT({ d: data }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime(`${ttlSeconds}s`).encrypt(getStateKey());
+}
+async function openEnc(token) {
+  try {
+    const { payload } = await jwtDecrypt(token, getStateKey());
+    return payload.d;
+  } catch {
+    return null;
+  }
+}
+var sealOAuthState = (d, ttl = 600) => sealEnc(d, ttl);
+var openOAuthState = (t) => openEnc(t);
+
+// src/passkey.ts
+import {
+  generateRegistrationOptions,
+  verifyRegistrationResponse,
+  generateAuthenticationOptions,
+  verifyAuthenticationResponse
+} from "@simplewebauthn/server";
+var b64u = { enc: (b) => Buffer.from(b).toString("base64url"), dec: (s) => new Uint8Array(Buffer.from(s, "base64url")) };
+function registrationOptions(a) {
+  return generateRegistrationOptions({
+    rpName: a.rpName,
+    rpID: a.rpID,
+    userID: new TextEncoder().encode(a.userId),
+    userName: a.userName,
+    attestationType: "none",
+    excludeCredentials: (a.existing ?? []).map((c) => ({ id: c.id, transports: c.transports })),
+    authenticatorSelection: { residentKey: "preferred", userVerification: "preferred" }
+  });
+}
+function authenticationOptions(a) {
+  return generateAuthenticationOptions({
+    rpID: a.rpID,
+    userVerification: "preferred",
+    allowCredentials: (a.allow ?? []).map((c) => ({ id: c.id, transports: c.transports }))
+  });
+}
+async function verifyRegistration(a) {
+  const v = await verifyRegistrationResponse({
+    response: a.response,
+    expectedChallenge: a.expectedChallenge,
+    expectedOrigin: a.origin,
+    expectedRPID: a.rpID
+  });
+  if (!v.verified || !v.registrationInfo) return { verified: false };
+  const c = v.registrationInfo.credential;
+  return { verified: true, credential: { id: c.id, publicKey: b64u.enc(c.publicKey), counter: c.counter, transports: c.transports } };
+}
+async function verifyAuthentication(a) {
+  const v = await verifyAuthenticationResponse({
+    response: a.response,
+    expectedChallenge: a.expectedChallenge,
+    expectedOrigin: a.origin,
+    expectedRPID: a.rpID,
+    credential: { id: a.credential.id, publicKey: b64u.dec(a.credential.publicKey), counter: a.credential.counter, transports: a.credential.transports }
+  });
+  return { verified: v.verified, newCounter: v.authenticationInfo?.newCounter };
+}
+
+// src/totp.ts
+import { TOTP, Secret } from "otpauth";
+function build(secretB32, label = "user", issuer = "PlanetLogin") {
+  return new TOTP({ issuer, label, algorithm: "SHA1", digits: 6, period: 30, secret: Secret.fromBase32(secretB32) });
+}
+function newTotpSecret() {
+  return new Secret({ size: 20 }).base32;
+}
+function totpKeyUri(secretB32, label, issuer = "PlanetLogin") {
+  return build(secretB32, label, issuer).toString();
+}
+function verifyTotp(secretB32, code) {
+  try {
+    return build(secretB32).validate({ token: String(code).trim(), window: 1 }) !== null;
+  } catch {
+    return false;
+  }
+}
+
+// src/flows/passwordLogin.ts
+async function passwordLogin(deps, input) {
+  let user;
+  try {
+    user = await deps.downstream.findUser(input.identifier);
+  } catch {
+    return { ok: false, code: "downstream_unavailable" };
+  }
+  if (!user || !user.passwordHash) {
+    return { ok: false, code: "invalid_credentials" };
+  }
+  const valid = await deps.verifyPassword(input.password, user.passwordHash);
+  if (!valid) {
+    return { ok: false, code: "invalid_credentials" };
+  }
+  if (user.totpEnabled) {
+    return { ok: "mfa", userId: user.id };
+  }
+  const token = await deps.signSession({
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    locale: input.locale ?? user.locale
+  });
+  return { ok: true, token, user: { id: user.id, email: user.email, name: user.name } };
+}
+
+// src/flows/magicLink.ts
+async function requestMagicLink(deps, input) {
+  try {
+    const user = await deps.downstream.findUser(input.identifier);
+    if (user) {
+      const token = await deps.signMagicToken(input.identifier);
+      const link = `${input.baseUrl.replace(/\/$/, "")}/auth/magic/verify?token=${encodeURIComponent(token)}`;
+      await deps.downstream.deliverMagic({ identifier: input.identifier, link, locale: input.locale });
+    }
+  } catch {
+  }
+  return { accepted: true };
+}
+async function verifyMagicLink(deps, input) {
+  const m = await deps.verifyMagicToken(input.token);
+  if (!m) return { ok: false, code: "invalid_token" };
+  const fresh = await deps.store.claimOnce(`magic:${m.jti}`, 900);
+  if (!fresh) return { ok: false, code: "invalid_token" };
+  const user = await deps.downstream.findUser(m.identifier).catch(() => null);
+  if (!user) return { ok: false, code: "invalid_token" };
+  const session = await deps.signSession({
+    sub: user.id,
+    email: user.email,
+    name: user.name,
+    locale: input.locale ?? user.locale
+  });
+  return { ok: true, token: session, user: { id: user.id, email: user.email, name: user.name } };
+}
+
+// src/flows/oauthLogin.ts
+async function oauthCallback(deps, input) {
+  try {
+    const accessToken = await exchangeCode(input.providerCfg, {
+      clientId: input.clientId,
+      clientSecret: input.clientSecret,
+      code: input.code,
+      codeVerifier: input.codeVerifier,
+      redirectUri: input.redirectUri
+    });
+    const id = await fetchProfile(input.providerCfg, accessToken);
+    if (!id.providerUserId) return { ok: false, code: "provider_error" };
+    const user = await deps.downstream.upsertUser({
+      provider: input.provider,
+      providerUserId: id.providerUserId,
+      email: id.email,
+      name: id.name
+    });
+    if (!user) return { ok: false, code: "provider_error" };
+    const token = await deps.signSession({
+      sub: user.id,
+      email: user.email ?? id.email,
+      name: user.name ?? id.name,
+      locale: input.locale
+    });
+    return { ok: true, token, user: { id: user.id, email: user.email, name: user.name } };
+  } catch {
+    return { ok: false, code: "provider_error" };
+  }
+}
+
+// src/flows/passkey.ts
+async function passkeyRegisterVerify(deps, input) {
+  const v = await deps.verifyRegistration({
+    response: input.response,
+    expectedChallenge: input.expectedChallenge,
+    origin: input.origin,
+    rpID: input.rpID
+  }).catch(() => ({ verified: false }));
+  if (!v.verified || !v.credential) return { ok: false, code: "invalid_credentials" };
+  await deps.downstream.passkeysSave({ userId: input.userId, credential: v.credential });
+  return { ok: true };
+}
+async function passkeyAuthVerify(deps, input) {
+  const credentialId = input.response?.id;
+  if (!credentialId) return { ok: false, code: "invalid_credentials" };
+  const found = await deps.downstream.passkeysFind({ credentialId }).catch(() => null);
+  const credential = found?.credentials?.find((c) => c.id === credentialId);
+  if (!found || !credential) return { ok: false, code: "invalid_credentials" };
+  const v = await deps.verifyAuthentication({
+    response: input.response,
+    expectedChallenge: input.expectedChallenge,
+    origin: input.origin,
+    rpID: input.rpID,
+    credential
+  }).catch(() => ({ verified: false }));
+  if (!v.verified) return { ok: false, code: "invalid_credentials" };
+  if (typeof v.newCounter === "number") {
+    await deps.downstream.passkeysSave({ userId: found.userId, credential: { ...credential, counter: v.newCounter } }).catch(() => {
+    });
+  }
+  const token = await deps.signSession({ sub: found.userId, locale: input.locale });
+  return { ok: true, token, user: { id: found.userId } };
+}
+
+// src/flows/totp.ts
+async function totpEnroll(deps, input) {
+  const secret = newTotpSecret();
+  await deps.downstream.totpSave({ userId: input.userId, secret, enabled: false });
+  return { secret, uri: totpKeyUri(secret, input.label, input.issuer) };
+}
+async function totpVerify(deps, input) {
+  const rec = await deps.downstream.totpGet({ userId: input.userId }).catch(() => null);
+  if (!rec?.secret) return { ok: false };
+  if (!verifyTotp(rec.secret, input.code)) return { ok: false };
+  if (!rec.enabled) await deps.downstream.totpSave({ userId: input.userId, secret: rec.secret, enabled: true });
+  return { ok: true };
+}
+export {
+  Downstream,
+  _stores,
+  authenticationOptions,
+  buildAuthUrl,
+  downstreamFromEnv,
+  exchangeCode,
+  fetchProfile,
+  getProvider,
+  getStore,
+  hashPassword,
+  jwks,
+  loadConfig,
+  newTotpSecret,
+  oauthCallback,
+  oauthStart,
+  openEnc,
+  openOAuthState,
+  passkeyAuthVerify,
+  passkeyRegisterVerify,
+  passwordLogin,
+  pkcePair,
+  publicConfig,
+  registrationOptions,
+  requestMagicLink,
+  sealEnc,
+  sealOAuthState,
+  signMagicToken,
+  signSession,
+  totpEnroll,
+  totpKeyUri,
+  totpVerify,
+  verifyAuthentication,
+  verifyMagicLink,
+  verifyMagicToken,
+  verifyPassword,
+  verifyRegistration,
+  verifySession,
+  verifyTotp
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@planetlogin/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "PlanetLogin auth core — framework-agnostic flows, JWT, crypto, downstream contract. Consumed by every flavor; the HTTP binding stays per-framework.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "mock": "tsx mock-downstream/server.ts"
+  },
+  "dependencies": {
+    "@simplewebauthn/server": "^13.3.2",
+    "bcryptjs": "^2.4.3",
+    "hash-wasm": "^4.11.0",
+    "jose": "^5.9.6",
+    "otpauth": "^9.3.4"
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^2.4.6",
+    "@types/node": "^26.0.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  }
+}