@planetlogin/core 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -13,7 +13,9 @@ interface SessionClaims {
     name?: string;
     locale?: Locale;
 }
-/** Public JWK Set served at GET /auth/.well-known/jwks.json. */
+type JwtAlg = 'EdDSA' | 'RS256' | 'ES256' | 'HS256';
+/** Public JWK Set served at GET /auth/.well-known/jwks.json. Empty for HS256
+ *  (symmetric secrets are shared out of band, never published). */
 declare function jwks(): Promise<{
     keys: JWK[];
 }>;
@@ -22,7 +24,7 @@ declare function signSession(claims: SessionClaims, opts?: {
     audience?: string;
     ttlSeconds?: number;
 }): Promise<string>;
-/** Verify a session token against our own JWKS (what a downstream service does). */
+/** Verify a session token against our own key material (what a downstream 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. */
@@ -134,6 +136,26 @@ interface PlanetLoginConfig {
     session?: {
         store?: 'none' | 'memory' | 'redis' | 'sqlite' | 'downstream';
     };
+    security?: {
+        cors?: {
+            origins?: string[];
+            credentials?: boolean;
+        };
+        rateLimit?: {
+            login?: {
+                limit: number;
+                windowSeconds: number;
+            };
+            magic?: {
+                limit: number;
+                windowSeconds: number;
+            };
+            totp?: {
+                limit: number;
+                windowSeconds: number;
+            };
+        };
+    };
 }
 declare function loadConfig(): PlanetLoginConfig;
 /** The public subset served at GET /auth/config (no secrets). */
@@ -193,13 +215,19 @@ interface SessionStore {
     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>;
+    /** Atomically increment a counter, setting its TTL on first touch; returns the
+     *  new count. Used by the rate limiter (fixed window). */
+    incr(key: string, ttlSeconds: number): Promise<number>;
 }
-/** No store: stateless. claimOnce always allows (single-use not enforced → TTL only). */
+/** No store: stateless. claimOnce always allows (single-use not enforced → TTL
+ *  only); incr always returns 1 → the rate limiter never blocks. Both real
+ *  single-use and rate limiting need a configured store (memory/redis/…). */
 declare class NoneStore implements SessionStore {
     get(): Promise<null>;
     set(): Promise<void>;
     delete(): Promise<void>;
     claimOnce(): Promise<boolean>;
+    incr(): Promise<number>;
 }
 declare class MemoryStore implements SessionStore {
     private m;
@@ -208,6 +236,7 @@ declare class MemoryStore implements SessionStore {
     set(key: string, value: string, ttlSeconds: number): Promise<void>;
     delete(key: string): Promise<void>;
     claimOnce(key: string, ttlSeconds: number): Promise<boolean>;
+    incr(key: string, ttlSeconds: number): Promise<number>;
 }
 type StoreKind = 'none' | 'memory' | 'redis' | 'sqlite' | 'downstream';
 /** Build the store from config. Only none+memory ship in this flavor; the rest
@@ -218,6 +247,57 @@ declare const _stores: {
     MemoryStore: typeof MemoryStore;
 };
 
+interface RateLimitRule {
+    /** Max attempts allowed within the window. */
+    limit: number;
+    /** Window length in seconds. */
+    windowSeconds: number;
+}
+interface RateLimitDecision {
+    ok: boolean;
+    /** Attempts left in the current window (0 when blocked). */
+    remaining: number;
+    /** Seconds the caller should wait before retrying (only meaningful when blocked). */
+    retryAfter: number;
+    limit: number;
+}
+/** Built-in defaults (per key, fixed window). Tuned for human use; override via
+ *  config.security.rateLimit or PLANETLOGIN_RATELIMIT_* env. */
+declare const DEFAULT_RULES: Record<string, RateLimitRule>;
+/**
+ * Consume one attempt for `key` under `rule`. `key` should already encode the
+ * action and a client discriminator (IP and/or identifier), e.g.
+ * `login:203.0.113.7` or `magic:user@x.com`. Builders below help.
+ */
+declare function rateLimit(store: SessionStore, key: string, rule: RateLimitRule): Promise<RateLimitDecision>;
+/** Resolve a rule for an action: config/env override, else built-in default. */
+declare function ruleFor(action: keyof typeof DEFAULT_RULES, overrides?: Partial<Record<string, RateLimitRule>>): RateLimitRule;
+/** Build a rate-limit key from an action + the client discriminators available.
+ *  Both IP and identifier are optional; whatever is present is hashed into the key. */
+declare function rlKey(action: string, parts: {
+    ip?: string | null;
+    identifier?: string | null;
+}): string;
+
+interface CorsConfig {
+    /** Allowed origins, or ['*'] to reflect any. */
+    origins: string[];
+    /** Send Access-Control-Allow-Credentials (cookies). Default true. */
+    credentials?: boolean;
+}
+/** Read the allowlist from env (flavors may merge with config). */
+declare function corsFromEnv(): CorsConfig;
+/** Is `origin` allowed under this config? */
+declare function originAllowed(origin: string | null | undefined, cfg: CorsConfig): boolean;
+/**
+ * CORS response headers for a given request origin. Returns {} when the origin
+ * isn't allowed (no CORS headers → the browser blocks the cross-origin read).
+ * Always includes `Vary: Origin` so caches don't serve the wrong ACAO.
+ */
+declare function corsHeaders(origin: string | null | undefined, cfg: CorsConfig): Record<string, string>;
+/** True for a CORS preflight (OPTIONS + Access-Control-Request-Method). */
+declare function isPreflight(method: string, requestMethodHeader: string | null | undefined): boolean;
+
 interface ProviderConfig {
     authorizeUrl: string;
     tokenUrl: string;
@@ -490,4 +570,4 @@ declare function totpVerify(deps: TotpDeps, input: {
     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 };
+export { type AuthResult, type AuthVerifyDeps, type CorsConfig, DEFAULT_RULES, Downstream, type DownstreamUser, type JwtAlg, 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 RateLimitDecision, type RateLimitRule, type RegisterResult, type RegisterVerifyDeps, type SessionClaims, type SessionStore, type StoreKind, type StoredCredential, type TotpDeps, _stores, authenticationOptions, buildAuthUrl, corsFromEnv, corsHeaders, downstreamFromEnv, exchangeCode, fetchProfile, getProvider, getStore, hashPassword, isPreflight, jwks, loadConfig, newTotpSecret, oauthCallback, oauthStart, openEnc, openOAuthState, originAllowed, passkeyAuthVerify, passkeyRegisterVerify, passwordLogin, pkcePair, publicConfig, rateLimit, registrationOptions, requestMagicLink, rlKey, ruleFor, sealEnc, sealOAuthState, signMagicToken, signSession, totpEnroll, totpKeyUri, totpVerify, verifyAuthentication, verifyMagicLink, verifyMagicToken, verifyPassword, verifyRegistration, verifySession, verifyTotp };

package/dist/index.js

@@ -86,47 +86,84 @@ import {
   jwtVerify,
   exportJWK,
   generateKeyPair,
+  generateSecret,
   importPKCS8,
   createLocalJWKSet
 } from "jose";
+import { readFileSync as readFileSync2 } from "fs";
+var ASYMMETRIC = ["EdDSA", "RS256", "ES256"];
 var cache = null;
+function resolveAlg() {
+  const a = process.env.PLANETLOGIN_JWT_ALG || "EdDSA";
+  if (!ASYMMETRIC.includes(a) && a !== "HS256") {
+    throw new Error(`Unsupported PLANETLOGIN_JWT_ALG "${a}" (use EdDSA|RS256|ES256|HS256)`);
+  }
+  return a;
+}
+function loadPrivatePem() {
+  const v = process.env.PLANETLOGIN_JWT_PRIVATE_KEY ?? process.env.PLANETLOGIN_JWT_PRIVATE_KEY_PEM;
+  if (!v) return null;
+  return v.includes("-----BEGIN") ? v : readFileSync2(v, "utf8");
+}
+function loadSecret() {
+  const v = process.env.PLANETLOGIN_JWT_SECRET;
+  if (!v) return null;
+  const raw = v.includes("\n") || v.length > 256 ? v : v.startsWith("/") ? readFileSync2(v, "utf8").trim() : v;
+  return new TextEncoder().encode(raw);
+}
 async function getKeys() {
   if (cache) return cache;
+  const alg = resolveAlg();
+  const kid = process.env.PLANETLOGIN_JWT_KID || "dev";
+  if (alg === "HS256") {
+    let secret = loadSecret();
+    if (!secret) {
+      console.warn("[planetlogin] WARNING: no PLANETLOGIN_JWT_SECRET \u2014 using an EPHEMERAL HS256 secret. Tokens die on restart and cannot be verified across instances. Do not use in production.");
+      secret = await generateSecret("HS256", { extractable: true });
+    }
+    cache = { alg, kid, sign: secret, verify: secret, pubJwk: null };
+    return cache;
+  }
   let priv;
-  const pem = process.env.PLANETLOGIN_JWT_PRIVATE_KEY_PEM;
+  const pem = loadPrivatePem();
   if (pem) {
-    priv = await importPKCS8(pem, "EdDSA");
+    priv = await importPKCS8(pem, alg);
   } else {
-    priv = (await generateKeyPair("EdDSA", { extractable: true })).privateKey;
+    console.warn(`[planetlogin] WARNING: no PLANETLOGIN_JWT_PRIVATE_KEY \u2014 using an EPHEMERAL ${alg} keypair. Do not use in production.`);
+    priv = (await generateKeyPair(alg, { 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 };
+  const { d, p, q, dp, dq, qi, ...pub } = full;
+  cache = { alg, kid, sign: priv, verify: priv, pubJwk: { ...pub, kid, use: "sig", alg } };
   return cache;
 }
 async function jwks() {
   const k = await getKeys();
-  return { keys: [k.pubJwk] };
+  return { keys: k.pubJwk ? [k.pubJwk] : [] };
+}
+async function verifier() {
+  const k = await getKeys();
+  if (k.alg === "HS256") return k.verify;
+  return createLocalJWKSet({ 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);
+  return new SignJWT({ email: claims.email, name: claims.name, locale: claims.locale }).setProtectedHeader({ alg: k.alg, kid: k.kid }).setSubject(claims.sub).setIssuedAt().setExpirationTime(`${opts.ttlSeconds ?? 3600}s`).setIssuer(opts.issuer ?? "planetlogin").setAudience(opts.audience ?? "planetlogin").sign(k.sign);
 }
 async function verifySession(token) {
-  const set = await jwks();
-  const keySet = createLocalJWKSet(set);
-  const { payload } = await jwtVerify(token, keySet, { issuer: "planetlogin", audience: "planetlogin" });
+  const { payload } = await jwtVerify(token, await verifier(), {
+    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);
+  return new SignJWT({ purpose: "magic" }).setProtectedHeader({ alg: k.alg, kid: k.kid }).setSubject(identifier).setJti(crypto.randomUUID()).setIssuedAt().setExpirationTime(`${ttlSeconds}s`).setIssuer("planetlogin").setAudience("planetlogin:magic").sign(k.sign);
 }
 async function verifyMagicToken(token) {
   try {
-    const set = await jwks();
-    const { payload } = await jwtVerify(token, createLocalJWKSet(set), {
+    const { payload } = await jwtVerify(token, await verifier(), {
       issuer: "planetlogin",
       audience: "planetlogin:magic"
     });
@@ -201,6 +238,9 @@ var NoneStore = class {
   async claimOnce() {
     return true;
   }
+  async incr() {
+    return 1;
+  }
 };
 var MemoryStore = class {
   m = /* @__PURE__ */ new Map();
@@ -227,6 +267,16 @@ var MemoryStore = class {
     await this.set(key, "1", ttlSeconds);
     return true;
   }
+  async incr(key, ttlSeconds) {
+    const e = this.alive(key);
+    if (!e) {
+      await this.set(key, "1", ttlSeconds);
+      return 1;
+    }
+    const n = Number(e.v) + 1;
+    e.v = String(n);
+    return n;
+  }
 };
 var cached = null;
 function getStore(kind = process.env.PLANETLOGIN_SESSION_STORE || "none") {
@@ -245,13 +295,75 @@ function getStore(kind = process.env.PLANETLOGIN_SESSION_STORE || "none") {
 }
 var _stores = { NoneStore, MemoryStore };
 
+// src/ratelimit.ts
+var DEFAULT_RULES = {
+  login: { limit: 10, windowSeconds: 300 },
+  // 10 / 5 min
+  magic: { limit: 5, windowSeconds: 900 },
+  // 5 / 15 min
+  totp: { limit: 10, windowSeconds: 300 }
+};
+async function rateLimit(store, key, rule) {
+  try {
+    const count = await store.incr(`rl:${key}`, rule.windowSeconds);
+    const remaining = Math.max(0, rule.limit - count);
+    if (count > rule.limit) {
+      return { ok: false, remaining: 0, retryAfter: rule.windowSeconds, limit: rule.limit };
+    }
+    return { ok: true, remaining, retryAfter: 0, limit: rule.limit };
+  } catch {
+    return { ok: true, remaining: rule.limit, retryAfter: 0, limit: rule.limit };
+  }
+}
+function ruleFor(action, overrides) {
+  const envLimit = process.env[`PLANETLOGIN_RATELIMIT_${action.toUpperCase()}_LIMIT`];
+  const envWindow = process.env[`PLANETLOGIN_RATELIMIT_${action.toUpperCase()}_WINDOW`];
+  const base = overrides?.[action] ?? DEFAULT_RULES[action];
+  return {
+    limit: envLimit ? Number(envLimit) : base.limit,
+    windowSeconds: envWindow ? Number(envWindow) : base.windowSeconds
+  };
+}
+function rlKey(action, parts) {
+  const disc = [parts.ip, parts.identifier].filter(Boolean).join("|") || "anon";
+  return `${action}:${disc}`;
+}
+
+// src/cors.ts
+var METHODS = "GET, POST, OPTIONS";
+var ALLOW_HEADERS = "content-type, authorization";
+function corsFromEnv() {
+  const raw = process.env.PLANETLOGIN_CORS_ORIGINS ?? "";
+  const origins = raw.split(",").map((s) => s.trim()).filter(Boolean);
+  const credentials = process.env.PLANETLOGIN_CORS_CREDENTIALS !== "false";
+  return { origins, credentials };
+}
+function originAllowed(origin, cfg2) {
+  if (!origin) return false;
+  if (cfg2.origins.includes(origin)) return true;
+  return cfg2.origins.includes("*") && cfg2.credentials === false;
+}
+function corsHeaders(origin, cfg2) {
+  const h = { vary: "Origin" };
+  if (!originAllowed(origin, cfg2)) return h;
+  h["access-control-allow-origin"] = cfg2.credentials === false && cfg2.origins.includes("*") ? "*" : origin;
+  if (cfg2.credentials !== false) h["access-control-allow-credentials"] = "true";
+  h["access-control-allow-methods"] = METHODS;
+  h["access-control-allow-headers"] = ALLOW_HEADERS;
+  h["access-control-max-age"] = "600";
+  return h;
+}
+function isPreflight(method, requestMethodHeader) {
+  return method === "OPTIONS" && !!requestMethodHeader;
+}
+
 // 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 };
+  const verifier2 = b64url(randomBytes(32));
+  const challenge = b64url(createHash("sha256").update(verifier2).digest());
+  return { verifier: verifier2, challenge };
 }
 var REGISTRY = {
   google: {
@@ -297,9 +409,9 @@ function buildAuthUrl(p, a) {
   return u.toString();
 }
 function oauthStart(p, a) {
-  const { verifier, challenge } = pkcePair();
+  const { verifier: verifier2, challenge } = pkcePair();
   const state = b64url(randomBytes(16));
-  return { url: buildAuthUrl(p, { ...a, state, challenge }), state, codeVerifier: verifier };
+  return { url: buildAuthUrl(p, { ...a, state, challenge }), state, codeVerifier: verifier2 };
 }
 async function exchangeCode(p, a) {
   const res = await fetch(p.tokenUrl, {
@@ -553,16 +665,20 @@ async function totpVerify(deps, input) {
   return { ok: true };
 }
 export {
+  DEFAULT_RULES,
   Downstream,
   _stores,
   authenticationOptions,
   buildAuthUrl,
+  corsFromEnv,
+  corsHeaders,
   downstreamFromEnv,
   exchangeCode,
   fetchProfile,
   getProvider,
   getStore,
   hashPassword,
+  isPreflight,
   jwks,
   loadConfig,
   newTotpSecret,
@@ -570,13 +686,17 @@ export {
   oauthStart,
   openEnc,
   openOAuthState,
+  originAllowed,
   passkeyAuthVerify,
   passkeyRegisterVerify,
   passwordLogin,
   pkcePair,
   publicConfig,
+  rateLimit,
   registrationOptions,
   requestMagicLink,
+  rlKey,
+  ruleFor,
   sealEnc,
   sealOAuthState,
   signMagicToken,

package/dist/keygen.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/keygen.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// bin/keygen.ts
+import { generateKeyPair, exportPKCS8, exportJWK } from "jose";
+import { writeFileSync } from "fs";
+var { privateKey, publicKey } = await generateKeyPair("EdDSA", { extractable: true });
+var pem = await exportPKCS8(privateKey);
+var pubJwk = await exportJWK(publicKey);
+var out = process.argv[2];
+if (out) {
+  writeFileSync(out, pem, { mode: 384 });
+  console.error(`Private key written to ${out} (chmod 600).`);
+  console.error(`
+Set:  PLANETLOGIN_JWT_PRIVATE_KEY=${out}`);
+} else {
+  process.stdout.write(pem);
+  console.error("\n# \u2191 EdDSA private key (PEM). Keep it secret. Then set one of:");
+  console.error("#   PLANETLOGIN_JWT_PRIVATE_KEY=/path/to/this/key.pem   (recommended: a secret file)");
+  console.error('#   PLANETLOGIN_JWT_PRIVATE_KEY="$(cat key.pem)"        (inline)');
+}
+console.error(`
+# Public key (the kid in your JWKS will be PLANETLOGIN_JWT_KID, default "dev"):`);
+console.error("# " + JSON.stringify({ ...pubJwk, use: "sig", alg: "EdDSA" }));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planetlogin/core",
-  "version": "0.1.0",
+  "version": "0.2.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": {
@@ -12,10 +12,17 @@
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "bin": {
+    "planetlogin-keygen": "./dist/keygen.js"
+  },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
+    "prepare": "tsup",
     "prepublishOnly": "tsup",
+    "keygen": "tsx bin/keygen.ts",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "mock": "tsx mock-downstream/server.ts"