@growth-labs/auth 0.7.0 → 0.7.2

package/src/utils/env-marker.ts

@@ -0,0 +1,39 @@
+const ENV_MARKER_PREFIX = 'env:'
+
+/**
+ * Pure resolver: takes an `"env:VAR_NAME"` marker and an env bag, returns
+ * the bound value or throws when the binding is missing / empty. Plain
+ * strings pass through unchanged. Kept pure (no `cloudflare:workers`
+ * import) so `src/config-store.ts` — and therefore the package main entry
+ * — stays clear of the runtime-only specifier and the pure-Node import
+ * gate stays green.
+ *
+ * The runtime env is supplied at call sites (middleware/routes) which can
+ * pull from `cloudflare:workers` themselves, OR by `src/runtime-bridge.ts`
+ * which stashes it onto `globalThis.__GL_AUTH_RUNTIME_ENV__` for
+ * `getConfig()` to read implicitly.
+ */
+export function resolveEnvMarker(
+	value: string | undefined,
+	env: Record<string, unknown>,
+): string | undefined {
+	if (typeof value !== 'string') return value
+	if (!value.startsWith(ENV_MARKER_PREFIX)) return value
+	const name = value.slice(ENV_MARKER_PREFIX.length)
+	if (!name) {
+		throw new Error(
+			'@growth-labs/auth: "env:" marker missing binding name (expected "env:VAR_NAME")',
+		)
+	}
+	const resolved = env[name]
+	if (typeof resolved !== 'string' || resolved.length === 0) {
+		throw new Error(
+			`@growth-labs/auth: env:${name} is not set in the Worker runtime env (declared as "env:${name}" in auth() options)`,
+		)
+	}
+	return resolved
+}
+
+export function isEnvMarker(value: unknown): boolean {
+	return typeof value === 'string' && value.startsWith(ENV_MARKER_PREFIX)
+}

package/src/utils/identity-cookie.ts

@@ -0,0 +1,138 @@
+import { base64url } from './encoding.js'
+
+const SECRET_BYTES = 32
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+export type IdentityCookieVerification = { valid: true; payload: string } | { valid: false }
+
+export async function signIdentityCookie(payload: string, secret: string): Promise<string> {
+	if (!payload) {
+		throw new Error('identity cookie payload is required')
+	}
+
+	const payloadBytes = encoder.encode(payload)
+	const key = await importSecret(secret)
+	if (!key) {
+		throw new Error('GL_IDENTITY_SECRET must be a base64-encoded 32-byte secret')
+	}
+
+	const signature = new Uint8Array(
+		await crypto.subtle.sign('HMAC', key, toArrayBuffer(payloadBytes)),
+	)
+	return `${base64url(payloadBytes)}.${base64url(signature)}`
+}
+
+export async function createIdentityCookiePayload(
+	subject: string,
+	secret: string,
+): Promise<string> {
+	if (!subject || !secret) {
+		throw new Error('identity cookie subject and secret are required')
+	}
+
+	const digest = new Uint8Array(
+		await crypto.subtle.digest('SHA-256', encoder.encode(subject + secret)),
+	)
+	return [...digest].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+export async function verifyIdentityCookie(
+	cookieValue: string,
+	secret: string,
+): Promise<IdentityCookieVerification> {
+	if (!cookieValue || !secret) {
+		return { valid: false }
+	}
+
+	const parts = cookieValue.split('.')
+	if (parts.length !== 2 || !parts[0] || !parts[1]) {
+		return { valid: false }
+	}
+
+	const payloadBytes = decodeBase64Url(parts[0])
+	const signatureBytes = decodeBase64Url(parts[1])
+	const key = await importSecret(secret)
+	if (!payloadBytes || !signatureBytes || !key) {
+		return { valid: false }
+	}
+
+	const expected = new Uint8Array(
+		await crypto.subtle.sign('HMAC', key, toArrayBuffer(payloadBytes)),
+	)
+	if (!timingSafeEqual(expected, signatureBytes)) {
+		return { valid: false }
+	}
+
+	return {
+		valid: true,
+		payload: decoder.decode(payloadBytes),
+	}
+}
+
+export function timingSafeEqual(left: ArrayLike<number>, right: ArrayLike<number>): boolean {
+	const length = Math.max(left.length, right.length)
+	let diff = left.length ^ right.length
+
+	for (let index = 0; index < length; index += 1) {
+		const leftByte = index < left.length ? left[index] : 0
+		const rightByte = index < right.length ? right[index] : 0
+		diff |= leftByte ^ rightByte
+	}
+
+	return diff === 0
+}
+
+async function importSecret(secret: string): Promise<CryptoKey | null> {
+	const bytes = decodeBase64(secret)
+	if (!bytes || bytes.byteLength !== SECRET_BYTES) {
+		return null
+	}
+
+	return crypto.subtle.importKey(
+		'raw',
+		toArrayBuffer(bytes),
+		{ name: 'HMAC', hash: 'SHA-256' },
+		false,
+		['sign'],
+	)
+}
+
+function decodeBase64(value: string): Uint8Array | null {
+	const normalized = value.trim().replace(/-/g, '+').replace(/_/g, '/')
+	if (!normalized) {
+		return null
+	}
+
+	try {
+		return binaryStringToBytes(atob(padBase64(normalized)))
+	} catch {
+		return null
+	}
+}
+
+function decodeBase64Url(value: string): Uint8Array | null {
+	if (!/^[A-Za-z0-9_-]+$/.test(value)) {
+		return null
+	}
+
+	return decodeBase64(value)
+}
+
+function padBase64(value: string): string {
+	return value.padEnd(value.length + ((4 - (value.length % 4)) % 4), '=')
+}
+
+function binaryStringToBytes(value: string): Uint8Array {
+	const bytes = new Uint8Array(value.length)
+	for (let index = 0; index < value.length; index += 1) {
+		bytes[index] = value.charCodeAt(index)
+	}
+	return bytes
+}
+
+function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+	const buffer = new ArrayBuffer(bytes.byteLength)
+	new Uint8Array(buffer).set(bytes)
+	return buffer
+}

package/src/utils/identity.ts

@@ -0,0 +1,240 @@
+// Identity-bridge helpers. The OpenAuth issuer this package targets emits
+// `sub` claims in the form `user:<ULID>` (e.g. `user:01KP8KA31Z3AGRCC578R9HXW0H`).
+// The unprefixed bare-ULID form was used in early issuer releases and is
+// no longer the contract.
+//
+// Two scenarios this module addresses:
+//
+// 1. **Sub-format drift detection.** A consumer's auth code that pulls
+//    the identity ID from a JWT should fail loudly if the issuer emits
+//    something that doesn't match the documented contract. Use
+//    `extractIdentityId` for the canonical extract-and-validate path.
+//
+// 2. **Legacy-row bridge migration.** A consumer that started using the
+//    issuer before the prefix change has rows in their `users` table
+//    whose `identity_user_id` column holds the bare ULID. After the
+//    issuer migration, every login by those users tries to bridge the
+//    new `user:<ULID>` to a row that holds the old `<ULID>` and throws
+//    `IdentityBridgeConflictError` from the consumer's bridge layer.
+//    `buildLegacyIdentitySubjectMigration` returns a parameterized SQL
+//    statement set the consumer can run as a one-shot data migration
+//    BEFORE deploying the issuer change. `findLegacyIdentitySubjects`
+//    is a canary query consumers can run any time to count remaining
+//    legacy rows.
+
+/**
+ * The literal prefix the issuer emits on every `sub` claim. Pinned as
+ * the contract for this package's auth flow. Any change is breaking
+ * and triggers a major bump.
+ */
+export const IDENTITY_SUBJECT_PREFIX = 'user:'
+
+/**
+ * Documented ULID shape: 26 chars of Crockford base32. The issuer
+ * uses ULIDv1 and never falls back to a generic UUID — pin the
+ * stricter pattern so drift is caught early.
+ */
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/
+
+/** Stable error code for sub-format drift. */
+export const IDENTITY_SUB_FORMAT_DRIFT = 'IDENTITY_SUB_FORMAT_DRIFT'
+
+export class IdentitySubFormatDriftError extends Error {
+	readonly code = IDENTITY_SUB_FORMAT_DRIFT
+	constructor(
+		message: string,
+		readonly observedSubject: string,
+	) {
+		super(message)
+		this.name = 'IdentitySubFormatDriftError'
+	}
+}
+
+/**
+ * Validate and unwrap a `sub` claim. Returns the bare ULID portion
+ * (the value Fronts stores in `users.identity_user_id` post-migration
+ * is the prefixed form; the bare ULID is the convenient handle for
+ * matching against business-side records that pre-date the prefix).
+ *
+ * Throws `IdentitySubFormatDriftError` when the subject does not match
+ * `user:<ULID>`. The error code `IDENTITY_SUB_FORMAT_DRIFT` is stable
+ * for observability matching.
+ */
+export function extractIdentityId(sub: string): string {
+	if (typeof sub !== 'string' || sub.length === 0) {
+		throw new IdentitySubFormatDriftError('JWT sub claim is missing or not a string', String(sub))
+	}
+	if (!sub.startsWith(IDENTITY_SUBJECT_PREFIX)) {
+		throw new IdentitySubFormatDriftError(
+			`JWT sub claim "${sub}" is missing the required "${IDENTITY_SUBJECT_PREFIX}" prefix. ` +
+				`The issuer contract pins the format as "${IDENTITY_SUBJECT_PREFIX}<ULID>". ` +
+				'If your issuer was migrated from an older release, see ' +
+				'packages-docs/auth-identity-bridge.md for the bridge-row migration helper.',
+			sub,
+		)
+	}
+	const id = sub.slice(IDENTITY_SUBJECT_PREFIX.length)
+	if (!ULID_PATTERN.test(id)) {
+		throw new IdentitySubFormatDriftError(
+			`JWT sub claim "${sub}" has the "${IDENTITY_SUBJECT_PREFIX}" prefix but the suffix ` +
+				'is not a valid 26-char Crockford base32 ULID.',
+			sub,
+		)
+	}
+	return id
+}
+
+/**
+ * Convenience: normalize either form to the canonical prefixed `sub`.
+ * Idempotent on already-prefixed input. Throws on invalid ULID.
+ *
+ * Useful inside a one-shot migration: pass each row's stored
+ * `identity_user_id` through this and write back the result.
+ */
+export function normalizeIdentitySubject(value: string): string {
+	if (typeof value !== 'string' || value.length === 0) {
+		throw new IdentitySubFormatDriftError('value is missing or not a string', String(value))
+	}
+	if (value.startsWith(IDENTITY_SUBJECT_PREFIX)) {
+		const id = value.slice(IDENTITY_SUBJECT_PREFIX.length)
+		if (!ULID_PATTERN.test(id)) {
+			throw new IdentitySubFormatDriftError(
+				`value "${value}" has the "${IDENTITY_SUBJECT_PREFIX}" prefix but the suffix is not a valid ULID.`,
+				value,
+			)
+		}
+		return value
+	}
+	if (!ULID_PATTERN.test(value)) {
+		throw new IdentitySubFormatDriftError(
+			`value "${value}" is neither a prefixed "${IDENTITY_SUBJECT_PREFIX}<ULID>" nor a valid bare ULID.`,
+			value,
+		)
+	}
+	return `${IDENTITY_SUBJECT_PREFIX}${value}`
+}
+
+// ─── Bridge migration helpers ───
+
+export interface BridgeMigrationOptions {
+	/** Table that holds the bridge column. Default: `users`. */
+	table?: string
+	/** Column that stores the issuer subject. Default: `identity_user_id`. */
+	column?: string
+}
+
+export interface BridgeMigrationStatement {
+	sql: string
+	bindings?: readonly unknown[]
+}
+
+/**
+ * Build the read-only canary query consumers run before deploying the
+ * issuer subject-format change. Returns the count of rows that hold
+ * legacy unprefixed values. A non-zero count means some logins will
+ * throw `IdentityBridgeConflictError` until those rows are rewritten
+ * by `buildLegacyIdentitySubjectMigration`.
+ *
+ * ```sql
+ * SELECT COUNT(*) FROM users WHERE identity_user_id IS NOT NULL
+ *   AND identity_user_id NOT LIKE 'user:%';
+ * ```
+ */
+export function buildLegacyIdentitySubjectCanary(
+	options: BridgeMigrationOptions = {},
+): BridgeMigrationStatement {
+	const { table = 'users', column = 'identity_user_id' } = options
+	assertSafeSqlIdentifier(table)
+	assertSafeSqlIdentifier(column)
+	return {
+		sql: `SELECT COUNT(*) AS legacy_count FROM ${table} WHERE ${column} IS NOT NULL AND ${column} NOT LIKE 'user:%'`,
+	}
+}
+
+/**
+ * Build the rewrite statement that prefixes legacy bare-ULID values to
+ * the canonical `user:<ULID>` form. Idempotent: rows whose value
+ * already starts with `user:` are not touched. Run as a one-shot
+ * migration BEFORE the issuer subject-format change goes live.
+ *
+ * ```sql
+ * UPDATE users
+ *   SET identity_user_id = 'user:' || identity_user_id
+ *   WHERE identity_user_id IS NOT NULL
+ *     AND identity_user_id NOT LIKE 'user:%';
+ * ```
+ *
+ * D1 / SQLite syntax. Adapt the concatenation operator (`||`) for
+ * other engines if you fork.
+ */
+export function buildLegacyIdentitySubjectMigration(
+	options: BridgeMigrationOptions = {},
+): BridgeMigrationStatement {
+	const { table = 'users', column = 'identity_user_id' } = options
+	assertSafeSqlIdentifier(table)
+	assertSafeSqlIdentifier(column)
+	return {
+		sql:
+			`UPDATE ${table} SET ${column} = 'user:' || ${column} ` +
+			`WHERE ${column} IS NOT NULL AND ${column} NOT LIKE 'user:%'`,
+	}
+}
+
+/**
+ * D1-binding-compatible: count legacy rows. Designed for consumer
+ * code like:
+ *
+ * ```ts
+ * const count = await findLegacyIdentitySubjects(env.SITE_DB)
+ * if (count > 0) throw new Error(`${count} rows need migration`)
+ * ```
+ */
+interface D1Like {
+	prepare(sql: string): {
+		first<T = unknown>(): Promise<T | null>
+	}
+}
+
+export async function findLegacyIdentitySubjects(
+	db: D1Like,
+	options: BridgeMigrationOptions = {},
+): Promise<number> {
+	const { sql } = buildLegacyIdentitySubjectCanary(options)
+	const row = await db.prepare(sql).first<{ legacy_count: number }>()
+	return row?.legacy_count ?? 0
+}
+
+/**
+ * D1-binding-compatible: rewrite legacy rows in place. Returns the
+ * number of rows updated.
+ *
+ * ```ts
+ * const rewritten = await rewriteLegacyIdentitySubjects(env.SITE_DB)
+ * console.log(`Migrated ${rewritten} rows`)
+ * ```
+ */
+interface D1RunLike {
+	prepare(sql: string): {
+		run(): Promise<{ meta?: { changes?: number; rows_written?: number } }>
+	}
+}
+
+export async function rewriteLegacyIdentitySubjects(
+	db: D1RunLike,
+	options: BridgeMigrationOptions = {},
+): Promise<number> {
+	const { sql } = buildLegacyIdentitySubjectMigration(options)
+	const result = await db.prepare(sql).run()
+	return result?.meta?.changes ?? result?.meta?.rows_written ?? 0
+}
+
+// ─── Internal ───
+
+function assertSafeSqlIdentifier(value: string): void {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+		throw new Error(
+			`@growth-labs/auth: identifier "${value}" is not a safe SQL identifier ` +
+				'(letters, digits, underscores; must not start with a digit).',
+		)
+	}
+}

package/src/utils/index.ts

@@ -0,0 +1,19 @@
+export { emitAuthEvent, trackAuthEvent } from './analytics.js'
+export {
+	type BridgeMigrationOptions,
+	type BridgeMigrationStatement,
+	buildLegacyIdentitySubjectCanary,
+	buildLegacyIdentitySubjectMigration,
+	extractIdentityId,
+	findLegacyIdentitySubjects,
+	IDENTITY_SUB_FORMAT_DRIFT,
+	IDENTITY_SUBJECT_PREFIX,
+	IdentitySubFormatDriftError,
+	normalizeIdentitySubject,
+	rewriteLegacyIdentitySubjects,
+} from './identity.js'
+export { signIdentityCookie, verifyIdentityCookie } from './identity-cookie.js'
+export { getAuthorizationUrl, getMagicLinkUrl, getPasswordLoginUrl } from './openauth.js'
+export { createPKCEChallenge, generatePKCE } from './pkce.js'
+export { generateState, verifyState } from './state.js'
+export type { VerifiedClaims } from './tokens.js'

package/src/utils/issuer.ts

@@ -0,0 +1,7 @@
+import type { ResolvedAuthOptions } from '../options.js'
+
+export function resolveInternalIssuer(
+	options: Pick<ResolvedAuthOptions, 'issuer' | 'issuerInternal'>,
+): string {
+	return options.issuerInternal ?? options.issuer
+}

package/src/utils/openauth.ts

@@ -0,0 +1,163 @@
+import { getConfig } from '../config-store.js'
+import type { TokenExchangeResult } from '../types.js'
+import { createClientSecretBasicAuthHeader, resolveClientSecret } from './client-secret.js'
+import { resolveInternalIssuer } from './issuer.js'
+import { generatePKCE } from './pkce.js'
+import { generateState } from './state.js'
+import { decodeJwtPayload, extractTokenClaims } from './tokens.js'
+
+export interface AuthFlow {
+	verifier: string
+	challenge: string
+	state: string
+	clientId: string
+	redirectUri: string
+}
+
+export async function createAuthFlow(context: { url: URL }): Promise<AuthFlow> {
+	const options = getConfig()
+	const { verifier, challenge } = await generatePKCE()
+	const state = generateState()
+
+	return {
+		verifier,
+		challenge,
+		state,
+		clientId: options.clientId || context.url.hostname,
+		redirectUri: new URL(options.callbackPath, context.url.origin).toString(),
+	}
+}
+
+export async function getAuthorizationUrl(
+	context: { url: URL },
+	provider: string,
+	_redirectPath: string,
+	authFlow?: AuthFlow,
+): Promise<{ url: string; pkceVerifier: string; state: string }> {
+	const options = getConfig()
+	const flow = authFlow ?? (await createAuthFlow(context))
+
+	const params = new URLSearchParams({
+		response_type: 'code',
+		client_id: flow.clientId,
+		redirect_uri: flow.redirectUri,
+		scope: 'openid email profile',
+		state: flow.state,
+		code_challenge: flow.challenge,
+		code_challenge_method: 'S256',
+		provider,
+	})
+	if (options.resource) params.set('resource', options.resource)
+
+	return {
+		url: `${options.issuer}/authorize?${params}`,
+		pkceVerifier: flow.verifier,
+		state: flow.state,
+	}
+}
+
+export function getPasswordLoginUrl(_context: { url: URL }): string {
+	const options = getConfig()
+	return `${options.issuer}/authorize/password`
+}
+
+export function getMagicLinkUrl(_context: { url: URL }): string {
+	const options = getConfig()
+	return `${options.issuer}/authorize/email-code`
+}
+
+export function getForgotPasswordUrl(): string {
+	const options = getConfig()
+	return `${options.issuer}/forgot-password`
+}
+
+export function getResetPasswordUrl(): string {
+	const options = getConfig()
+	return `${options.issuer}/reset-password`
+}
+
+export async function exchangeCode(
+	callbackUrl: URL,
+	code: string,
+	codeVerifier: string,
+	providerFromCookie?: TokenExchangeResult['provider'],
+): Promise<TokenExchangeResult | null> {
+	const options = getConfig()
+	const issuer = resolveInternalIssuer(options)
+	const clientId = options.clientId || callbackUrl.hostname
+	const redirectUri = new URL(options.callbackPath, callbackUrl.origin).toString()
+	const clientSecret = resolveClientSecret(options.clientSecret)
+	const headers: Record<string, string> = {
+		'Content-Type': 'application/x-www-form-urlencoded',
+	}
+	if (clientSecret) {
+		headers.Authorization = createClientSecretBasicAuthHeader(clientId, clientSecret)
+	}
+	const body = new URLSearchParams({
+		grant_type: 'authorization_code',
+		code,
+		code_verifier: codeVerifier,
+		redirect_uri: redirectUri,
+		client_id: clientId,
+	})
+	if (options.resource) body.set('resource', options.resource)
+
+	try {
+		const response = await fetch(`${issuer}/token`, {
+			method: 'POST',
+			headers,
+			body: body.toString(),
+		})
+
+		if (!response.ok) return null
+
+		const data = (await response.json()) as {
+			access_token: string
+			refresh_token: string
+		}
+
+		const claims = extractTokenClaims(decodeJwtPayload(data.access_token))
+
+		return {
+			accessToken: data.access_token,
+			refreshToken: data.refresh_token,
+			isNewUser: claims.isNewUser,
+			provider: providerFromCookie ?? 'unknown',
+			claims: {
+				sub: claims.sub,
+				email: claims.email,
+				name: claims.name,
+				image: claims.image,
+			},
+		}
+	} catch {
+		return null
+	}
+}
+
+export async function revokeToken(
+	refreshToken: string,
+	clientId?: string,
+	clientSecret?: string,
+): Promise<void> {
+	const options = getConfig()
+	const issuer = resolveInternalIssuer(options)
+	const headers: Record<string, string> = { 'Content-Type': 'application/x-www-form-urlencoded' }
+	if (clientId && clientSecret) {
+		headers.Authorization = createClientSecretBasicAuthHeader(clientId, clientSecret)
+	}
+
+	try {
+		await fetch(`${issuer}/revoke`, {
+			method: 'POST',
+			headers,
+			body: new URLSearchParams({
+				token: refreshToken,
+				token_type_hint: 'refresh_token',
+				...(clientId && { client_id: clientId }),
+			}).toString(),
+		})
+	} catch {
+		// Fire and forget — ignore errors
+	}
+}

package/src/utils/pkce.ts

@@ -0,0 +1,16 @@
+import { base64url } from './encoding.js'
+
+export async function createPKCEChallenge(verifier: string): Promise<string> {
+	const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+	return base64url(new Uint8Array(digest))
+}
+
+export async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+	const array = new Uint8Array(32)
+	crypto.getRandomValues(array)
+	const verifier = base64url(array)
+
+	const challenge = await createPKCEChallenge(verifier)
+
+	return { verifier, challenge }
+}

package/src/utils/state.ts

@@ -0,0 +1,20 @@
+import { base64url } from './encoding.js'
+
+export function generateState(): string {
+	const array = new Uint8Array(32)
+	crypto.getRandomValues(array)
+	return base64url(array)
+}
+
+export function verifyState(returned: string, stored: string): boolean {
+	if (!returned || !stored) return false
+	if (returned.length !== stored.length) return false
+
+	const a = new TextEncoder().encode(returned)
+	const b = new TextEncoder().encode(stored)
+	let diff = 0
+	for (let i = 0; i < a.length; i++) {
+		diff |= a[i] ^ b[i]
+	}
+	return diff === 0
+}