@planetlogin/core 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface Locale {
     language?: string;
     timezone?: string;
     country?: string;
+    lat?: number;
+    lon?: number;
 }
 interface SessionClaims {
     sub: string;
@@ -24,7 +26,8 @@ declare function signSession(claims: SessionClaims, opts?: {
     audience?: string;
     ttlSeconds?: number;
 }): Promise<string>;
-/** Verify a session token against our own key material (what a downstream does). */
+/** Verify a session token against our own key material (what a downstream does).
+ *  Transparently decrypts a JWE-wrapped token first when encryption is on. */
 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. */
@@ -41,6 +44,13 @@ interface DownstreamUser {
     locale?: Locale;
     totpEnabled?: boolean;
 }
+/** Per-user, dev-owned preferences (spec §4). `locale` is the typed, first-class
+ *  piece PlanetLogin reads/writes (fly-to + i18n); `data` is an open bag the
+ *  integrator can store any "that kind of info" in. */
+interface UserPreferences {
+    locale?: Locale;
+    data?: Record<string, unknown>;
+}
 declare class Downstream {
     private baseUrl;
     private secret;
@@ -86,6 +96,13 @@ declare class Downstream {
         secret: string;
         enabled: boolean;
     }): Promise<unknown>;
+    /** Preferences (spec §4): per-user locale + open data bag. Null when none. */
+    preferencesGet(query: {
+        userId: string;
+    }): Promise<UserPreferences | null>;
+    preferencesSave(data: {
+        userId: string;
+    } & UserPreferences): Promise<unknown>;
 }
 
 interface PlanetLoginConfig {
@@ -127,11 +144,16 @@ interface PlanetLoginConfig {
         showSearch?: boolean;
         autoSpin?: boolean;
     };
+    locale?: {
+        persist?: boolean;
+        flyToOnLogin?: boolean;
+    };
     token?: {
         issuer?: string;
         audience?: string;
         ttlSeconds?: number;
         algorithm?: 'EdDSA' | 'RS256' | 'ES256' | 'HS256';
+        encrypt?: boolean;
     };
     session?: {
         store?: 'none' | 'memory' | 'redis' | 'sqlite' | 'downstream';
@@ -198,6 +220,9 @@ declare function publicConfig(c?: PlanetLoginConfig): {
         showSearch?: boolean;
         autoSpin?: boolean;
     };
+    locale: {
+        flyToOnLogin: boolean;
+    };
 };
 declare function downstreamFromEnv(): Downstream;
 
@@ -427,6 +452,24 @@ type PasswordLoginResult = {
 };
 declare function passwordLogin(deps: PasswordLoginDeps, input: PasswordLoginInput): Promise<PasswordLoginResult>;
 
+interface PreferencesDeps {
+    downstream: Pick<Downstream, 'preferencesGet' | 'preferencesSave'>;
+}
+/** Keep only the known, well-typed locale fields (drop anything else). */
+declare function sanitizeLocale(input: unknown): Locale | undefined;
+/** Read the user's saved preferences. Always resolves (empty object if none/error). */
+declare function getPreferences(deps: PreferencesDeps, input: {
+    userId: string;
+}): Promise<UserPreferences>;
+/** Write the user's preferences. No-op when there's nothing valid to write. */
+declare function savePreferences(deps: PreferencesDeps, input: {
+    userId: string;
+    locale?: unknown;
+    data?: unknown;
+}): Promise<{
+    saved: boolean;
+}>;
+
 interface MagicRequestDeps {
     downstream: Downstream;
     signMagicToken: (identifier: string) => Promise<string>;
@@ -570,4 +613,4 @@ declare function totpVerify(deps: TotpDeps, input: {
     ok: boolean;
 }>;
 
-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 };
+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 PreferencesDeps, type ProviderConfig, type RateLimitDecision, type RateLimitRule, type RegisterResult, type RegisterVerifyDeps, type SessionClaims, type SessionStore, type StoreKind, type StoredCredential, type TotpDeps, type UserPreferences, _stores, authenticationOptions, buildAuthUrl, corsFromEnv, corsHeaders, downstreamFromEnv, exchangeCode, fetchProfile, getPreferences, getProvider, getStore, hashPassword, isPreflight, jwks, loadConfig, newTotpSecret, oauthCallback, oauthStart, openEnc, openOAuthState, originAllowed, passkeyAuthVerify, passkeyRegisterVerify, passwordLogin, pkcePair, publicConfig, rateLimit, registrationOptions, requestMagicLink, rlKey, ruleFor, sanitizeLocale, savePreferences, sealEnc, sealOAuthState, signMagicToken, signSession, totpEnroll, totpKeyUri, totpVerify, verifyAuthentication, verifyMagicLink, verifyMagicToken, verifyPassword, verifyRegistration, verifySession, verifyTotp };

package/dist/index.js

@@ -55,6 +55,13 @@ var Downstream = class {
   totpSave(data) {
     return this.call("/totp/save", data);
   }
+  /** Preferences (spec §4): per-user locale + open data bag. Null when none. */
+  preferencesGet(query) {
+    return this.call("/preferences/find", query);
+  }
+  preferencesSave(data) {
+    return this.call("/preferences/save", data);
+  }
 };
 
 // src/config.ts
@@ -71,7 +78,15 @@ function loadConfig() {
   return cfg;
 }
 function publicConfig(c = loadConfig()) {
-  return { spec: c.spec, brand: c.brand, providers: c.providers, copy: c.copy ?? {}, layout: c.layout ?? {} };
+  return {
+    spec: c.spec,
+    brand: c.brand,
+    providers: c.providers,
+    copy: c.copy ?? {},
+    layout: c.layout ?? {},
+    // Only the client-relevant gate (flyToOnLogin drives the post-login fly-to).
+    locale: { flyToOnLogin: c.locale?.flyToOnLogin ?? false }
+  };
 }
 function downstreamFromEnv() {
   const url = process.env.PLANETLOGIN_DOWNSTREAM_URL;
@@ -88,7 +103,10 @@ import {
   generateKeyPair,
   generateSecret,
   importPKCS8,
-  createLocalJWKSet
+  createLocalJWKSet,
+  CompactEncrypt,
+  compactDecrypt,
+  base64url
 } from "jose";
 import { readFileSync as readFileSync2 } from "fs";
 var ASYMMETRIC = ["EdDSA", "RS256", "ES256"];
@@ -146,12 +164,38 @@ async function verifier() {
   if (k.alg === "HS256") return k.verify;
   return createLocalJWKSet({ keys: [k.pubJwk] });
 }
+var jweKey = null;
+function encryptEnabled() {
+  return process.env.PLANETLOGIN_JWT_ENCRYPT === "true";
+}
+function getJweKey() {
+  if (jweKey) return jweKey;
+  const env = process.env.PLANETLOGIN_JWE_KEY;
+  if (env) {
+    jweKey = base64url.decode(env);
+    if (jweKey.length !== 32) throw new Error("PLANETLOGIN_JWE_KEY must decode to 32 bytes (base64url)");
+  } else {
+    console.warn("[planetlogin] WARNING: PLANETLOGIN_JWT_ENCRYPT is on but no PLANETLOGIN_JWE_KEY \u2014 using an EPHEMERAL key. Tokens cannot be decrypted across instances/restarts. Do not use in production.");
+    jweKey = crypto.getRandomValues(new Uint8Array(32));
+  }
+  return jweKey;
+}
+async function maybeEncrypt(jws) {
+  if (!encryptEnabled()) return jws;
+  return new CompactEncrypt(new TextEncoder().encode(jws)).setProtectedHeader({ alg: "dir", enc: "A256GCM", cty: "JWT" }).encrypt(getJweKey());
+}
+async function maybeDecrypt(token) {
+  if (token.split(".").length !== 5) return token;
+  const { plaintext } = await compactDecrypt(token, getJweKey());
+  return new TextDecoder().decode(plaintext);
+}
 async function signSession(claims, opts = {}) {
   const k = await getKeys();
-  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);
+  const jws = await 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);
+  return maybeEncrypt(jws);
 }
 async function verifySession(token) {
-  const { payload } = await jwtVerify(token, await verifier(), {
+  const { payload } = await jwtVerify(await maybeDecrypt(token), await verifier(), {
     issuer: "planetlogin",
     audience: "planetlogin"
   });
@@ -440,12 +484,12 @@ async function fetchProfile(p, accessToken) {
 }
 
 // src/oauthState.ts
-import { EncryptJWT, jwtDecrypt, base64url } from "jose";
+import { EncryptJWT, jwtDecrypt, base64url as base64url2 } 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));
+  stateKey = env ? base64url2.decode(env) : crypto.getRandomValues(new Uint8Array(32));
   if (stateKey.length !== 32) throw new Error("PLANETLOGIN_STATE_KEY must decode to 32 bytes");
   return stateKey;
 }
@@ -557,6 +601,30 @@ async function passwordLogin(deps, input) {
   return { ok: true, token, user: { id: user.id, email: user.email, name: user.name } };
 }
 
+// src/flows/preferences.ts
+function sanitizeLocale(input) {
+  if (!input || typeof input !== "object") return void 0;
+  const i = input;
+  const out = {};
+  if (typeof i.language === "string") out.language = i.language.slice(0, 16);
+  if (typeof i.timezone === "string") out.timezone = i.timezone.slice(0, 64);
+  if (typeof i.country === "string") out.country = i.country.slice(0, 2).toUpperCase();
+  if (typeof i.lat === "number" && Number.isFinite(i.lat)) out.lat = i.lat;
+  if (typeof i.lon === "number" && Number.isFinite(i.lon)) out.lon = i.lon;
+  return Object.keys(out).length ? out : void 0;
+}
+async function getPreferences(deps, input) {
+  const p = await deps.downstream.preferencesGet({ userId: input.userId }).catch(() => null);
+  return p ?? {};
+}
+async function savePreferences(deps, input) {
+  const locale = sanitizeLocale(input.locale);
+  const data = input.data && typeof input.data === "object" && !Array.isArray(input.data) ? input.data : void 0;
+  if (!locale && !data) return { saved: false };
+  await deps.downstream.preferencesSave({ userId: input.userId, ...locale ? { locale } : {}, ...data ? { data } : {} });
+  return { saved: true };
+}
+
 // src/flows/magicLink.ts
 async function requestMagicLink(deps, input) {
   try {
@@ -675,6 +743,7 @@ export {
   downstreamFromEnv,
   exchangeCode,
   fetchProfile,
+  getPreferences,
   getProvider,
   getStore,
   hashPassword,
@@ -697,6 +766,8 @@ export {
   requestMagicLink,
   rlKey,
   ruleFor,
+  sanitizeLocale,
+  savePreferences,
   sealEnc,
   sealOAuthState,
   signMagicToken,

package/dist/keygen.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 
 // bin/keygen.ts
-import { generateKeyPair, exportPKCS8, exportJWK } from "jose";
+import { generateKeyPair, exportPKCS8, exportJWK, base64url } from "jose";
 import { writeFileSync } from "fs";
+if (process.argv.includes("--jwe")) {
+  const key = base64url.encode(crypto.getRandomValues(new Uint8Array(32)));
+  process.stdout.write(key + "\n");
+  console.error("\n# \u2191 32-byte JWE key (base64url). Shared out of band with services that read claims. Then set:");
+  console.error("#   PLANETLOGIN_JWT_ENCRYPT=true");
+  console.error(`#   PLANETLOGIN_JWE_KEY=${key}`);
+  process.exit(0);
+}
 var { privateKey, publicKey } = await generateKeyPair("EdDSA", { extractable: true });
 var pem = await exportPKCS8(privateKey);
 var pubJwk = await exportJWK(publicKey);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planetlogin/core",
-  "version": "0.2.0",
+  "version": "0.4.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": {