@everystack/auth 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# @everystack/auth
+
+JWT auth for Expo apps. Zero runtime dependencies. SQL-compatible. Edge-verifiable.
+
+## Why
+
+Most JWT libraries (`jose`, `jsonwebtoken`, ...) are large dependencies that:
+
+1. Don't run in CloudFront Functions (no `Buffer`, `TextEncoder`, `crypto.subtle`)
+2. Aren't byte-compatible with a Postgres-only implementation
+3. Pull in WebCrypto polyfills you don't need on Node
+
+This package provides one HS256 envelope that runs in three places — Node, Postgres, and CloudFront Functions — and produces byte-identical tokens in all three.
+
+## Three Deployment Modes
+
+| Mode | Mint tokens | Verify tokens | Use when |
+|------|-------------|---------------|----------|
+| **JS-only** | Lambda (Node) | Lambda + CFF (edge) | Standard Expo + SST app |
+| **SQL-only** | Postgres (`jwt_sign`) | Postgres (`jwt_verify`) | Pure PostgREST, no Lambda |
+| **Hybrid** | Either | Either | DB issues long-lived refresh, edge verifies short-lived access |
+
+All three produce the same wire format: `header.payload.signature`, base64url, no padding, HS256.
+
+## Install
+
+```bash
+pnpm add @everystack/auth
+```
+
+Zero runtime dependencies. `drizzle-orm` and `react` are optional peer deps for the schema and client exports.
+
+## Entry Points
+
+| Export | Purpose |
+|--------|---------|
+| `@everystack/auth` | High-level handlers: `createAuthHandlers`, `verifyToken`, OAuth providers |
+| `@everystack/auth/jwt` | Low-level `createJwt({ secret, hmac })` — runtime-agnostic envelope |
+| `@everystack/auth/jwt/node` | `hmacNode` — HMAC backed by `node:crypto` |
+| `@everystack/auth/jwt/web` | `hmacWeb` — HMAC backed by `crypto.subtle` |
+| `@everystack/auth/jwt/sql` | SQL helpers for the Postgres twin (`jwt_sign`, `jwt_verify`) |
+| `@everystack/auth/oauth` | `verifyOidcToken` (RS256+JWKS), Google, Apple |
+| `@everystack/auth/cff` | `generateCffVerifier()` — emits a verifier as a string for CloudFront Functions |
+| `@everystack/auth/client` | React `AuthProvider`, `useAuth` |
+| `@everystack/auth/api` | API client wired with auto-refresh |
+| `@everystack/auth/schema` | Drizzle schema for `refresh_tokens`, `oauth_accounts` |
+
+## The Envelope
+
+Library owns:
+
+- `{"alg":"HS256","typ":"JWT"}` header (literal, not negotiated)
+- base64url encoding (RFC 4648 §5, no padding)
+- `iat` / `exp` math, configurable TTL and clock skew
+- Optional `jti`
+- Constant-time signature compare
+- Algorithm pinning (rejects `alg=none`, `alg=HS512`, RSA confusion)
+
+App owns:
+
+- Claim shape (`sub` / `user_id` / whatever your DB uses)
+- Role accessor (where to read role from claims)
+- Subject accessor
+
+```typescript
+import { createJwt } from '@everystack/auth/jwt';
+import { hmacNode } from '@everystack/auth/jwt/node';
+
+const jwt = createJwt({
+  secret: process.env.JWT_SECRET!,
+  hmac: hmacNode,
+  ttlSec: 3600,
+  clockSkewSec: 30,
+  includeJti: true,
+  // Optional accessors so the verifier knows where to look in your custom claim shape:
+  getSubject: (c) => c.user_id ?? c.sub,
+  getRole:    (c) => c.role,
+  getExpiry:  (c) => c.exp,
+});
+
+const token  = await jwt.sign({ user_id: 'u_123', role: 'admin', email: 'a@b.c' });
+const claims = await jwt.verify(token);  // null if invalid/expired
+```
+
+## High-Level Handlers
+
+```typescript
+import { createAuthHandlers, createAppleProvider, createGoogleProvider } from '@everystack/auth';
+import { refreshTokens, oauthAccounts } from '@everystack/auth/schema';
+import { createDb, getJwtSecret } from '@everystack/server/db';
+import * as schema from '../db/schema';
+
+const { db } = createDb(schema);
+const auth = createAuthHandlers(
+  db,
+  { ...schema, refreshTokens, oauthAccounts },
+  getJwtSecret(),
+  {
+    oauth: {
+      providers: [
+        createAppleProvider({ clientId: 'com.yourapp.id' }),
+        createGoogleProvider({ clientId: 'your-client-id.apps.googleusercontent.com' }),
+      ],
+    },
+  }
+);
+```
+
+| Handler | Method | Body | Returns |
+|---------|--------|------|---------|
+| `signup` | POST | `{ email, password, username, displayName }` | `{ token, refreshToken, user }` |
+| `signin` | POST | `{ email, password }` | `{ token, refreshToken, user }` |
+| `refresh` | POST | `{ refreshToken }` | `{ token, refreshToken }` |
+| `oauth` | POST | `{ provider, token }` | `{ token, refreshToken, user }` |
+| `verifyToken` | — | token string | `TokenPayload \| null` |
+| `revokeRefreshTokens` | — | `userId` | `void` |
+
+Defaults: HS256, access TTL 1h, refresh TTL 7d.
+
+## OAuth (RS256 + JWKS)
+
+```typescript
+import { verifyOidcToken, createJwksCache } from '@everystack/auth/oauth';
+
+const jwks = createJwksCache({
+  fetcher: () => fetch('https://www.googleapis.com/oauth2/v3/certs').then(r => r.json()),
+  ttlMs: 3600_000,
+});
+
+const claims = await verifyOidcToken(idToken, {
+  issuer: ['https://accounts.google.com', 'accounts.google.com'],
+  audience: process.env.GOOGLE_CLIENT_ID!,
+  jwks,
+});
+```
+
+The `jwks` cache deduplicates inflight fetches and force-refreshes when an unknown `kid` is seen. Algorithm is pinned to RS256.
+
+Built-in providers (`createGoogleProvider`, `createAppleProvider`) wrap the above with the right issuer/JWKS URI and map provider claims to a uniform `OAuthUserInfo`.
+
+## Edge Verification (CloudFront Functions)
+
+CloudFront Functions run a strict ES2019 subset — no `Buffer`, no `TextEncoder`, no `atob`/`btoa`, no `crypto.subtle`. Only `crypto.createHmac('sha256').digest('base64')` is available.
+
+`generateCffVerifier()` emits a self-contained verifier as a string you can embed in your CFF source:
+
+```typescript
+import { generateCffVerifier } from '@everystack/auth/cff';
+
+const source = generateCffVerifier({
+  functionName: 'verifyJwt',
+  clockSkewSec: 30,
+});
+
+// `source` is portable JS — concatenate into your CFF function file.
+```
+
+The emitted `verifyJwt(token, secret)` returns `{ payload }` or throws. It pins HS256, requires `typ:"JWT"`, requires numeric `exp`, and applies clock skew.
+
+For SST users, `@everystack/server/cdn` provides a higher-level helper:
+
+```typescript
+import { createAuthFunction } from '@everystack/server/cdn';
+
+const auth = createAuthFunction({
+  secret: $output(secret.value),
+  publicPaths: ['/api/auth/', '/api/health', '/api/updates'],
+  roles: {
+    posts:    { read: 'public',         write: 'authenticated' },
+    comments: { read: 'authenticated',  write: 'authenticated' },
+    '*':      { read: 'authenticated',  write: 'admin' },
+  },
+  roleHierarchy: ['public', 'authenticated', 'admin'],
+});
+
+new sst.aws.Router('Router', {
+  edge: { viewerRequest: { injection: auth.injection } },
+});
+```
+
+The injection runs at the edge before any Lambda hop. It returns 401/403 directly when auth fails — no cold start, no API Gateway round trip.
+
+### Edge revocation tradeoff
+
+Edge verification trusts the signature; it cannot consult a revocation list without a network call (which defeats the point). Mitigations:
+
+- Keep **access tokens short** (≤ 15 min recommended for edge-verified setups)
+- Keep **refresh tokens long-lived in DB** with revocation
+- Sign-out / password change → revoke refresh tokens, access tokens expire on their own
+
+## SQL Twin
+
+`@everystack/auth/jwt/sql` ships pgcrypto-based functions that produce byte-identical tokens to the JS path:
+
+- `jwt_sign(claims jsonb, secret text)` → `text`
+- `jwt_verify(token text, secret text)` → `jsonb`
+
+Use this if you want PostgREST to mint tokens directly from a `sign_in` SQL function, or to verify tokens inside RLS policies. Conformance tests guarantee byte-identical output for the same `(claims, secret)` pair.
+
+## Client
+
+```tsx
+import { AuthProvider, useAuth } from '@everystack/auth/client';
+
+function App() {
+  return <AuthProvider><YourApp /></AuthProvider>;
+}
+
+function Login() {
+  const { signIn, signUp, signOut, user, isLoading } = useAuth();
+  // ...
+}
+```
+
+`storage` exposes `getToken()`, `getRefresh()`, `getUser()`, `save()`, `clear()`. Keys: `everystack-token`, `everystack-refresh`, `everystack-user`.
+
+## API Client (`@everystack/auth/api`)
+
+Pre-configured `@everystack/api/client` instance:
+
+- Auto-injects `Authorization: Bearer ...`
+- On 401 → calls `/api/auth/refresh`, deduplicates concurrent refreshes, retries original request
+- `rpc<T>(name, body?)` for `/api/rpc/*` calls
+
+## Password Hashing
+
+- `hashPassword(password)` — bcrypt cost 12 (`bcryptjs`, pure JS). Throws on empty input or >72 UTF-8 bytes (no silent truncation).
+- `verifyPassword(password, stored)` — accepts `$2a$` / `$2b$` / `$2y$` prefixes; returns `false` (never throws) on malformed input.
+- SQL twin: byte-compatible with pgcrypto `crypt(p, gen_salt('bf', 12))`.
+
+## Types
+
+```typescript
+interface TokenPayload {
+  sub: string;
+  email: string;
+  role: string;
+  // ...your custom claims
+}
+```
+
+## Peer Dependencies
+
+- `drizzle-orm` (optional) — only for `@everystack/auth/schema` and the high-level handlers
+- `react` (optional) — only for `@everystack/auth/client`
+- `@everystack/api` (optional) — only for `@everystack/auth/api`
+
+No JWT library dependency.
+
+---
+
+Part of [everystack](https://github.com/scalable-technology/everystack) — a self-hosted application stack for Expo apps on AWS.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,104 @@
+{
+  "name": "@everystack/auth",
+  "version": "0.1.0",
+  "description": "JWT authentication handlers, password hashing, and React auth context",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./client": {
+      "types": "./src/client/index.tsx",
+      "default": "./src/client/index.tsx"
+    },
+    "./api": {
+      "types": "./src/api.ts",
+      "default": "./src/api.ts"
+    },
+    "./schema": {
+      "types": "./src/schema.ts",
+      "default": "./src/schema.ts"
+    },
+    "./sql": {
+      "types": "./src/sql.ts",
+      "default": "./src/sql.ts"
+    },
+    "./postgres": {
+      "types": "./src/postgres.ts",
+      "default": "./src/postgres.ts"
+    },
+    "./jwt": {
+      "types": "./src/jwt/index.ts",
+      "default": "./src/jwt/index.ts"
+    },
+    "./jwt/node": {
+      "types": "./src/jwt/hmac-node.ts",
+      "default": "./src/jwt/hmac-node.ts"
+    },
+    "./jwt/web": {
+      "types": "./src/jwt/hmac-web.ts",
+      "default": "./src/jwt/hmac-web.ts"
+    },
+    "./jwt/sql": {
+      "default": "./src/jwt/jwt.sql"
+    },
+    "./oauth": {
+      "types": "./src/oauth/index.ts",
+      "default": "./src/oauth/index.ts"
+    },
+    "./cookies": {
+      "types": "./src/cookies.ts",
+      "default": "./src/cookies.ts"
+    },
+    "./context": {
+      "types": "./src/context.ts",
+      "default": "./src/context.ts"
+    },
+    "./cff": {
+      "types": "./src/cff/index.ts",
+      "default": "./src/cff/index.ts"
+    }
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.3"
+  },
+  "peerDependencies": {
+    "@everystack/api": ">=0.1.0",
+    "drizzle-orm": ">=0.30.0",
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@everystack/api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/bcryptjs": "^3.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "drizzle-orm": "^0.41.0",
+    "jest": "^29.7.0",
+    "postgres": "^3.4.0",
+    "ts-jest": "^29.3.0",
+    "typescript": "^5.7.0",
+    "@everystack/api": "0.1.0"
+  },
+  "scripts": {
+    "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
+    "build": "tsc --build",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/api.ts

@@ -0,0 +1,65 @@
+/**
+ * @everystack/auth/api — Pre-configured API client with auth token management.
+ *
+ * Token storage keys match the auth client exactly so the API client
+ * always reads the latest token after signin/signup.
+ *
+ * Usage:
+ *   import { api, rpc } from '@everystack/auth/api';
+ *
+ *   const { data } = await api.from('posts').select();
+ *   const result = await rpc('timeline', { limit: 20 });
+ */
+
+import { createClient } from '@everystack/api/client';
+
+const TOKEN_KEY = 'everystack-token';
+const REFRESH_KEY = 'everystack-refresh';
+
+export const api = createClient({
+  baseUrl: '/api',
+  getToken: () => {
+    try { return localStorage.getItem(TOKEN_KEY); } catch { return null; }
+  },
+  onTokenExpired: async () => {
+    try {
+      const refreshToken = localStorage.getItem(REFRESH_KEY);
+      if (!refreshToken) return null;
+      const res = await fetch('/api/auth/refresh', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ refreshToken }),
+      });
+      if (!res.ok) return null;
+      const body = await res.json();
+      localStorage.setItem(TOKEN_KEY, body.token);
+      localStorage.setItem(REFRESH_KEY, body.refreshToken);
+      return body.token;
+    } catch { return null; }
+  },
+});
+
+/**
+ * Call an RPC function on the handler.
+ */
+export async function rpc<T = unknown>(name: string, body?: unknown): Promise<T> {
+  const token = (() => {
+    try { return localStorage.getItem(TOKEN_KEY); } catch { return null; }
+  })();
+
+  const res = await fetch(`/api/rpc/${name}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: body ? JSON.stringify(body) : '{}',
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.message || `RPC ${name} failed: ${res.status}`);
+  }
+
+  return res.json();
+}

package/src/cff/index.ts

@@ -0,0 +1,157 @@
+/**
+ * @everystack/auth/cff — CloudFront Functions code generator.
+ *
+ * Emits a self-contained ES2019 source string that runs inside the CloudFront
+ * Functions runtime 2.0. Verifies HS256 JWTs minted by @everystack/auth/jwt
+ * (or by the SQL twin) and returns the decoded claims object, or null on any
+ * failure (tampered, expired, wrong alg, malformed, missing exp).
+ *
+ * The emitted code uses ONLY:
+ *   - Built-in `crypto.createHmac('sha256', secret)` (CFF runtime 2.0 builtin)
+ *   - Native String / JSON / Math / Date / parseInt
+ *
+ * It does NOT use Buffer, TextEncoder, atob, btoa, or any Node API.
+ */
+
+export interface CffGeneratorOptions {
+  /**
+   * Optional: name to give the exported verifier. Default 'verifyJwt'.
+   * Useful when bundling multiple verifiers in a single CFF.
+   */
+  functionName?: string;
+  /**
+   * Optional: maximum allowed clock skew (seconds) when checking exp. Default 30.
+   */
+  clockSkewSec?: number;
+}
+
+/**
+ * Compact verifier — same API as generateCffVerifier but ~1,200 bytes raw
+ * instead of ~3,700. Trades full UTF-8 decoding for ASCII-only
+ * String.fromCharCode (safe because JWT claims are always ASCII).
+ *
+ * Use this when the CloudFront Function size budget is tight.
+ */
+export function generateCompactCffVerifier(opts: CffGeneratorOptions = {}): string {
+  const fnName = opts.functionName ?? 'verifyJwt';
+  const skew = Number.isFinite(opts.clockSkewSec) ? Math.max(0, Math.floor(opts.clockSkewSec!)) : 30;
+
+  return `var _B64="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+var crypto=require("crypto");
+function _b64d(s){var o=[],i=0,n=s.length;while(i<n){var a=_B64.indexOf(s.charAt(i++)),b=_B64.indexOf(s.charAt(i++)),c=i<n?_B64.indexOf(s.charAt(i++)):-1,d=i<n?_B64.indexOf(s.charAt(i++)):-1;if(a<0||b<0)return"";o.push((a<<2)|(b>>4));if(c>=0)o.push(((b&15)<<4)|(c>>2));if(d>=0)o.push(((c&3)<<6)|d)}return String.fromCharCode.apply(null,o)}
+function ${fnName}(token,secret){if(typeof token!=="string"||!token)return null;var p=token.split(".");if(p.length!==3)return null;var h;try{h=JSON.parse(_b64d(p[0]))}catch(e){return null}if(!h||h.alg!=="HS256"||h.typ!=="JWT")return null;var exp=crypto.createHmac("sha256",secret).update(p[0]+"."+p[1]).digest("base64").replace(/\\+/g,"-").replace(/\\//g,"_").replace(/=+$/,"");if(exp.length!==p[2].length)return null;var df=0;for(var i=0;i<exp.length;i++)df|=exp.charCodeAt(i)^p[2].charCodeAt(i);if(df!==0)return null;var c;try{c=JSON.parse(_b64d(p[1]))}catch(e){return null}if(!c||typeof c!=="object")return null;if(typeof c.exp!=="number")return null;if(Math.floor(Date.now()/1000)>c.exp+${skew})return null;return c}
+`;
+}
+
+export function generateCffVerifier(opts: CffGeneratorOptions = {}): string {
+  const fnName = opts.functionName ?? 'verifyJwt';
+  const skew = Number.isFinite(opts.clockSkewSec) ? Math.max(0, Math.floor(opts.clockSkewSec!)) : 30;
+
+  return `// @everystack/auth/cff — generated HS256 verifier (CloudFront Functions runtime 2.0).
+// Returns claims object on success, null on any failure.
+// Pure ES2019 + crypto.createHmac('sha256', secret).digest('base64').
+var crypto = require('crypto');
+
+function ${fnName}(token, secret) {
+  if (typeof token !== 'string' || token.length === 0) return null;
+  var parts = token.split('.');
+  if (parts.length !== 3) return null;
+  var headerB64 = parts[0];
+  var payloadB64 = parts[1];
+  var sigB64 = parts[2];
+
+  // 1. Header check — must be exactly HS256+JWT.
+  var header;
+  try { header = JSON.parse(b64uDecodeToString(headerB64)); } catch (e) { return null; }
+  if (!header || header.alg !== 'HS256' || header.typ !== 'JWT') return null;
+
+  // 2. Recompute signature and constant-time compare.
+  var expected = b64ToB64u(
+    crypto.createHmac('sha256', secret).update(headerB64 + '.' + payloadB64).digest('base64')
+  );
+  if (!ctEq(expected, sigB64)) return null;
+
+  // 3. Decode payload and validate exp.
+  var claims;
+  try { claims = JSON.parse(b64uDecodeToString(payloadB64)); } catch (e) { return null; }
+  if (!claims || typeof claims !== 'object') return null;
+  if (typeof claims.exp !== 'number') return null;
+  var now = Math.floor(Date.now() / 1000);
+  if (now > claims.exp + ${skew}) return null;
+
+  return claims;
+}
+
+// base64 -> base64url (RFC 4648 §5, no padding).
+function b64ToB64u(s) {
+  return s.replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '');
+}
+
+// base64url -> string (UTF-8 decode of bytes).
+// CFF runtime 2.0 has no atob; we decode manually.
+var B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+function b64uDecodeToString(input) {
+  // Build a lookup table once (cached on function).
+  if (!b64uDecodeToString._lut) {
+    var lut = {};
+    for (var i = 0; i < B64_ALPHABET.length; i++) lut[B64_ALPHABET.charAt(i)] = i;
+    b64uDecodeToString._lut = lut;
+  }
+  var lut = b64uDecodeToString._lut;
+  var bytes = [];
+  var len = input.length;
+  var i = 0;
+  while (i < len) {
+    var c1 = lut[input.charAt(i++)];
+    var c2 = lut[input.charAt(i++)];
+    var c3 = i < len ? lut[input.charAt(i++)] : -1;
+    var c4 = i < len ? lut[input.charAt(i++)] : -1;
+    if (c1 === undefined || c2 === undefined) return '';
+    bytes.push((c1 << 2) | (c2 >> 4));
+    if (c3 !== -1 && c3 !== undefined) bytes.push(((c2 & 15) << 4) | (c3 >> 2));
+    if (c4 !== -1 && c4 !== undefined) bytes.push(((c3 & 3) << 6) | c4);
+  }
+  return utf8BytesToString(bytes);
+}
+
+// UTF-8 byte array -> JS string.
+function utf8BytesToString(bytes) {
+  var out = '';
+  var i = 0;
+  var n = bytes.length;
+  while (i < n) {
+    var b1 = bytes[i++];
+    if (b1 < 0x80) {
+      out += String.fromCharCode(b1);
+    } else if (b1 < 0xc0) {
+      // continuation byte without leader — invalid; emit replacement.
+      out += '\\uFFFD';
+    } else if (b1 < 0xe0) {
+      var b2 = bytes[i++] & 0x3f;
+      out += String.fromCharCode(((b1 & 0x1f) << 6) | b2);
+    } else if (b1 < 0xf0) {
+      var c2 = bytes[i++] & 0x3f;
+      var c3 = bytes[i++] & 0x3f;
+      out += String.fromCharCode(((b1 & 0x0f) << 12) | (c2 << 6) | c3);
+    } else {
+      // 4-byte sequence -> surrogate pair.
+      var d2 = bytes[i++] & 0x3f;
+      var d3 = bytes[i++] & 0x3f;
+      var d4 = bytes[i++] & 0x3f;
+      var cp = ((b1 & 0x07) << 18) | (d2 << 12) | (d3 << 6) | d4;
+      cp -= 0x10000;
+      out += String.fromCharCode(0xd800 + (cp >> 10), 0xdc00 + (cp & 0x3ff));
+    }
+  }
+  return out;
+}
+
+// Constant-time string compare.
+function ctEq(a, b) {
+  if (a.length !== b.length) return false;
+  var diff = 0;
+  for (var i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+`;
+}