@octane-xplat/auth 0.10.0 → 0.11.0

package/src/hosted.ts

@@ -0,0 +1,392 @@
+// Hosted-auth client — the session transport for native apps that sign in
+// through a hosted page. Sign-in is a PKCE-bound system-browser ceremony
+// (authSession): the flow's `begin` issues a backend attempt and returns
+// the hosted URL, the browser returns on a custom scheme, and `complete`
+// redeems the callback into a short-lived access token (Bearer on API
+// calls) plus a durable session credential (refresh + sign-out).
+//
+// The client owns the ceremony lifecycle and credential storage; the
+// `HostedAuthFlow` adapter owns where requests go and what they carry —
+// no backend endpoints or field names are baked in here.
+//
+// Everything is string plumbing — no DOM globals (URL/Headers/Request types
+// are not declared in the native typecheck program, invariant 4).
+import { authSession, random } from '@octane-xplat/platform'
+import { secureStorage } from '@octane-xplat/secure-storage'
+import { bytesToBase64Url } from './base64'
+import { sha256, utf8Bytes } from './sha256'
+import type {
+	HostedAuth,
+	HostedAuthAttempt,
+	HostedAuthConfig,
+	HostedAuthCredentialStore,
+	HostedAuthCredentials,
+	HostedAuthFetch,
+	HostedAuthRequestInit,
+	HostedAuthSignInResult,
+} from './types'
+
+const DEFAULT_STORAGE_KEY = 'hosted-auth'
+// Re-mint the access token this far ahead of its server-side expiry.
+const REFRESH_SKEW_MS = 30_000
+
+export function createHostedAuth(config: HostedAuthConfig): HostedAuth {
+	const apiOrigin = normalizeOrigin(config.apiOrigin)
+	const authorizePath = config.authorizePath ?? defaultAuthorizePath
+	const storageKey = config.storageKey ?? DEFAULT_STORAGE_KEY
+	const now = config.now ?? Date.now
+	const transport: HostedAuthFetch =
+		config.fetch ??
+		((url, init) => {
+			const impl = (globalThis as { fetch?: HostedAuthFetch }).fetch
+			if (!impl) {
+				return Promise.reject(new Error('hostedAuth: fetch is unavailable on this target'))
+			}
+
+			return impl(url, init)
+		})
+
+	let credentials: HostedAuthCredentials | null | undefined
+	let refreshPromise: Promise<string | null> | null = null
+
+	function store(): HostedAuthCredentialStore | null {
+		return config.storage ?? secureStorage.impl
+	}
+
+	async function persist(creds: HostedAuthCredentials | null) {
+		credentials = creds
+		const storage = store()
+		if (!storage) {
+			return
+		}
+
+		try {
+			if (creds) {
+				await storage.set(storageKey, JSON.stringify(creds))
+			} else {
+				await storage.remove(storageKey)
+			}
+		} catch {
+			// Persistence is best-effort — the session still lives in memory.
+		}
+	}
+
+	async function load(): Promise<HostedAuthCredentials | null> {
+		if (credentials !== undefined) {
+			return credentials
+		}
+
+		const storage = store()
+		if (!storage) {
+			credentials = null
+			return null
+		}
+
+		try {
+			const raw = await storage.get(storageKey)
+			const parsed = raw ? parseCredentials(raw) : null
+			// Assign only if still unrestored — a signIn/persist landing mid-read wins.
+			if (credentials === undefined) {
+				credentials = parsed
+			}
+
+			if (!parsed && raw) {
+				await storage.remove(storageKey)
+			}
+		} catch {
+			// Unreadable storage is treated as empty.
+			credentials ??= null
+		}
+
+		return credentials ?? null
+	}
+
+	async function refresh(): Promise<string | null> {
+		const creds = await load()
+		if (!creds || !config.flow.refresh) {
+			return null
+		}
+
+		const next = await config.flow.refresh(creds, { fetch: transport })
+		if (!isCredentials(next)) {
+			// The durable session is expired or revoked — local state is dead.
+			await persist(null)
+			return null
+		}
+
+		await persist(next)
+		return next.token
+	}
+
+	function refreshedAccessToken(): Promise<string | null> {
+		refreshPromise ??= refresh().finally(() => {
+			refreshPromise = null
+		})
+
+		return refreshPromise
+	}
+
+	async function getAccessToken(): Promise<string | null> {
+		const creds = await load()
+		if (!creds) {
+			return null
+		}
+
+		if (creds.expiresAt - now() > REFRESH_SKEW_MS) {
+			return creds.token
+		}
+
+		return refreshedAccessToken()
+	}
+
+	async function signIn(): Promise<HostedAuthSignInResult> {
+		const session = config.authSession ?? {
+			supported: authSession.supported,
+			open: (url, options) => {
+				const impl = authSession.impl
+				if (!impl) {
+					return Promise.resolve({
+						type: 'error' as const,
+						message: 'hostedAuth: hosted sign-in is not supported on this target',
+					})
+				}
+
+				return impl.open(url, options)
+			},
+		}
+
+		if (!session.supported || !random.supported) {
+			return {
+				status: 'error',
+				message: 'hostedAuth: hosted sign-in is not supported on this target',
+			}
+		}
+
+		const verifier = bytesToBase64Url(random.bytes(32))
+		const pkce = { challenge: bytesToBase64Url(sha256(utf8Bytes(verifier))), verifier }
+
+		let attempt: HostedAuthAttempt
+		try {
+			attempt = await config.flow.begin({ fetch: transport, pkce })
+		} catch (error) {
+			return { status: 'error', message: errorMessage(error) }
+		}
+
+		const result = await session.open(attempt.url, { callbackScheme: attempt.callbackScheme })
+		if (result.type === 'cancel') {
+			return { status: 'cancelled' }
+		}
+
+		if (result.type === 'error') {
+			return { status: 'error', message: result.message }
+		}
+
+		if (attempt.state !== undefined && queryParam(result.url, 'state') !== attempt.state) {
+			return {
+				status: 'error',
+				message: 'hostedAuth: callback did not carry the expected state',
+			}
+		}
+
+		try {
+			const creds = await config.flow.complete(result.url, attempt, {
+				fetch: transport,
+				pkce,
+			})
+
+			if (!isCredentials(creds)) {
+				return {
+					status: 'error',
+					message: 'hostedAuth: sign-in did not produce credentials',
+				}
+			}
+
+			await persist(creds)
+			return { status: 'success' }
+		} catch (error) {
+			return { status: 'error', message: errorMessage(error) }
+		}
+	}
+
+	async function fetchWithAuth(url: string, init?: HostedAuthRequestInit) {
+		const pathname = apiPath(url, apiOrigin)
+
+		if (pathname === null || !authorizePath(pathname)) {
+			return transport(url, init)
+		}
+
+		const target = url.startsWith('/') ? `${apiOrigin}${url}` : url
+		const token = await getAccessToken()
+		const response = await transport(target, token === null ? init : withBearer(init, token))
+
+		if (!isInvalidAccessTokenChallenge(response.status, response.headers)) {
+			return response
+		}
+
+		const refreshed = await refreshedAccessToken()
+		if (refreshed === null) {
+			return response
+		}
+
+		return transport(target, withBearer(init, refreshed))
+	}
+
+	async function signOut() {
+		const creds = await load()
+		await persist(null)
+		if (!creds || !config.flow.revoke) {
+			return
+		}
+
+		try {
+			await config.flow.revoke(creds, { fetch: transport })
+		} catch {
+			// Revocation is best-effort — local credentials are already cleared.
+		}
+	}
+
+	return {
+		get supported() {
+			return (config.authSession?.supported ?? authSession.supported) && random.supported
+		},
+		restore: async () => ((await load()) ? 'authenticated' : 'unauthenticated'),
+		signIn,
+		getAccessToken,
+		fetch: fetchWithAuth,
+		signOut,
+	}
+}
+
+function normalizeOrigin(value: string): string {
+	const trimmed = value.trim().replace(/\/+$/u, '')
+	if (!/^https?:\/\/[^\s/?#]+$/u.test(trimmed)) {
+		throw new TypeError(
+			`hostedAuth: apiOrigin must be an HTTP(S) origin without path or parameters, got ${JSON.stringify(value)}`,
+		)
+	}
+
+	return trimmed
+}
+
+/** `POST` a JSON body through the flow's transport. */
+export function postJson(transport: HostedAuthFetch, url: string, body: Record<string, string>) {
+	return transport(url, {
+		body: JSON.stringify(body),
+		headers: { 'content-type': 'application/json' },
+		method: 'POST',
+	})
+}
+
+/** `?name=value` extraction without URLSearchParams (not in the native program). */
+export function queryParam(url: string, name: string): string | null {
+	const start = url.indexOf('?')
+	if (start === -1) {
+		return null
+	}
+
+	const query = url.slice(start + 1).split('#', 1)[0]
+	for (const pair of query.split('&')) {
+		const eq = pair.indexOf('=')
+		const key = eq === -1 ? pair : pair.slice(0, eq)
+		if (key === name) {
+			return eq === -1 ? '' : decodeURIComponent(pair.slice(eq + 1).replaceAll('+', ' '))
+		}
+	}
+
+	return null
+}
+
+function isCredentials(value: unknown): value is HostedAuthCredentials {
+	const creds = value as HostedAuthCredentials | null
+	return (
+		!!creds &&
+		typeof creds.token === 'string' &&
+		typeof creds.expiresAt === 'number' &&
+		typeof creds.sessionToken === 'string'
+	)
+}
+
+function parseCredentials(raw: string): HostedAuthCredentials | null {
+	try {
+		const parsed = JSON.parse(raw) as Partial<HostedAuthCredentials>
+		if (isCredentials(parsed)) {
+			return { expiresAt: parsed.expiresAt, sessionToken: parsed.sessionToken, token: parsed.token }
+		}
+	} catch {
+		// fall through
+	}
+
+	return null
+}
+
+/**
+ * Pathname of `url` when it belongs to `apiOrigin` — `null` for other
+ * origins. Relative (`/path`) and origin-prefixed inputs both resolve.
+ */
+function apiPath(url: string, apiOrigin: string): string | null {
+	if (url.startsWith('//')) {
+		return null
+	}
+
+	let path: string
+	if (url.startsWith('/')) {
+		path = url
+	} else if (url.startsWith(apiOrigin + '/') || url === apiOrigin) {
+		path = url.slice(apiOrigin.length) || '/'
+	} else {
+		return null
+	}
+
+	const end = path.search(/[?#]/u)
+	return end === -1 ? path : path.slice(0, end)
+}
+
+/**
+ * Default `authorizePath` — every same-origin path under `/api/` except the
+ * `/api/auth` mount hosted backends reserve for auth endpoints.
+ */
+function defaultAuthorizePath(pathname: string): boolean {
+	return (
+		pathname.startsWith('/api/') && !(pathname === '/api/auth' || pathname.startsWith('/api/auth/'))
+	)
+}
+
+function withBearer(init: HostedAuthRequestInit | undefined, token: string): HostedAuthRequestInit {
+	const headers: Record<string, string> = {}
+	const incoming = init?.headers
+	if (incoming) {
+		if (Symbol.iterator in incoming) {
+			for (const [name, value] of incoming) {
+				headers[name.toLowerCase()] = value
+			}
+		} else {
+			for (const name of Object.keys(incoming)) {
+				headers[name.toLowerCase()] = incoming[name]
+			}
+		}
+	}
+
+	headers.authorization = `Bearer ${token}`
+	return { ...init, headers }
+}
+
+/**
+ * RFC 6750 `401 + WWW-Authenticate: Bearer error="invalid_token"` — the
+ * challenge that distinguishes a dead access token from an ordinary
+ * authorization failure.
+ */
+function isInvalidAccessTokenChallenge(
+	status: number,
+	headers: { get(name: string): string | null },
+): boolean {
+	if (status !== 401) {
+		return false
+	}
+
+	const challenge = headers.get('www-authenticate')
+	return !!challenge && /error\s*=\s*"invalid_token"/iu.test(challenge)
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : 'hostedAuth: the hosted ceremony failed'
+}

package/src/index.macos.ts

@@ -2,6 +2,7 @@ export { appleAuth } from './apple.macos'
 export { googleAuth } from './google.macos'
 export { AppleSignInButton } from './AppleSignInButton.macos.tsrx'
 export { GoogleSignInButton } from './GoogleSignInButton.macos.tsrx'
+export { createHostedAuth, postJson, queryParam } from './hosted'
 export type {
 	AppleAuth,
 	AppleAuthConfig,
@@ -11,6 +12,21 @@ export type {
 	AppleSignInOptions,
 	AuthCredential,
 	AuthUser,
+	HostedAuth,
+	HostedAuthAttempt,
+	HostedAuthConfig,
+	HostedAuthCredentialStore,
+	HostedAuthCredentials,
+	HostedAuthFetch,
+	HostedAuthFlow,
+	HostedAuthFlowContext,
+	HostedAuthPkce,
+	HostedAuthRequestInit,
+	HostedAuthResponse,
+	HostedAuthSession,
+	HostedAuthSessionResult,
+	HostedAuthSignInResult,
+	HostedAuthStatus,
 	GoogleAuth,
 	GoogleAuthConfig,
 	GoogleHostedAuthFlow,

package/src/index.ts

@@ -4,6 +4,7 @@ export { appleAuth } from './apple'
 export { googleAuth } from './google'
 export { AppleSignInButton } from './AppleSignInButton.tsrx'
 export { GoogleSignInButton } from './GoogleSignInButton.tsrx'
+export { createHostedAuth, postJson, queryParam } from './hosted'
 export type {
 	AppleAuth,
 	AppleAuthConfig,
@@ -13,6 +14,21 @@ export type {
 	AppleSignInOptions,
 	AuthCredential,
 	AuthUser,
+	HostedAuth,
+	HostedAuthAttempt,
+	HostedAuthConfig,
+	HostedAuthCredentialStore,
+	HostedAuthCredentials,
+	HostedAuthFetch,
+	HostedAuthFlow,
+	HostedAuthFlowContext,
+	HostedAuthPkce,
+	HostedAuthRequestInit,
+	HostedAuthResponse,
+	HostedAuthSession,
+	HostedAuthSessionResult,
+	HostedAuthSignInResult,
+	HostedAuthStatus,
 	GoogleAuth,
 	GoogleAuthConfig,
 	GoogleHostedAuthFlow,

package/src/index.web.ts

@@ -4,6 +4,7 @@ export { appleAuth } from './apple.web'
 export { googleAuth } from './google.web'
 export { AppleSignInButton } from './AppleSignInButton.web.tsrx'
 export { GoogleSignInButton } from './GoogleSignInButton.web.tsrx'
+export { createHostedAuth, postJson, queryParam } from './hosted'
 export type {
 	AppleAuth,
 	AppleAuthConfig,
@@ -13,6 +14,21 @@ export type {
 	AppleSignInOptions,
 	AuthCredential,
 	AuthUser,
+	HostedAuth,
+	HostedAuthAttempt,
+	HostedAuthConfig,
+	HostedAuthCredentialStore,
+	HostedAuthCredentials,
+	HostedAuthFetch,
+	HostedAuthFlow,
+	HostedAuthFlowContext,
+	HostedAuthPkce,
+	HostedAuthRequestInit,
+	HostedAuthResponse,
+	HostedAuthSession,
+	HostedAuthSessionResult,
+	HostedAuthSignInResult,
+	HostedAuthStatus,
 	GoogleAuth,
 	GoogleAuthConfig,
 	GoogleHostedAuthFlow,

package/src/sha256.ts

@@ -0,0 +1,118 @@
+// FIPS 180-4 SHA-256 — pure TypeScript so every target hashes identically.
+// The native runtime has no crypto.subtle, and TextEncoder is not declared
+// cross-target, so UTF-8 encoding is manual. Kept dependency-free on purpose
+// (same rationale as the apple.macos.ts copy this was extracted from).
+
+export function utf8Bytes(input: string): Uint8Array {
+	const bytes: number[] = []
+	for (let i = 0; i < input.length; i++) {
+		let cp = input.charCodeAt(i)
+		if (cp >= 0xd800 && cp <= 0xdbff && i + 1 < input.length) {
+			const low = input.charCodeAt(i + 1)
+			if (low >= 0xdc00 && low <= 0xdfff) {
+				cp = 0x10000 + ((cp - 0xd800) << 10) + (low - 0xdc00)
+				i++
+			}
+		}
+
+		if (cp < 0x80) {
+			bytes.push(cp)
+		} else if (cp < 0x800) {
+			bytes.push(0xc0 | (cp >> 6), 0x80 | (cp & 0x3f))
+		} else if (cp < 0x10000) {
+			bytes.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f))
+		} else {
+			bytes.push(
+				0xf0 | (cp >> 18),
+				0x80 | ((cp >> 12) & 0x3f),
+				0x80 | ((cp >> 6) & 0x3f),
+				0x80 | (cp & 0x3f),
+			)
+		}
+	}
+
+	return new Uint8Array(bytes)
+}
+
+export function sha256(bytes: Uint8Array): Uint8Array {
+	const K = new Uint32Array([
+		0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+		0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+		0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+		0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+		0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+		0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+		0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+		0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+	])
+
+	const H = new Uint32Array([
+		0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+	])
+
+	const bitLen = bytes.length * 8
+	const padded = new Uint8Array((bytes.length + 9 + 63) & ~63)
+	padded.set(bytes)
+	padded[bytes.length] = 0x80
+	const dv = new DataView(padded.buffer)
+	dv.setUint32(padded.length - 8, Math.floor(bitLen / 0x100000000))
+	dv.setUint32(padded.length - 4, bitLen >>> 0)
+	const w = new Uint32Array(64)
+	for (let block = 0; block < padded.length; block += 64) {
+		for (let t = 0; t < 16; t++) {
+			w[t] = dv.getUint32(block + t * 4)
+		}
+
+		for (let t = 16; t < 64; t++) {
+			const s0 =
+				((w[t - 15] >>> 7) | (w[t - 15] << 25)) ^
+				((w[t - 15] >>> 18) | (w[t - 15] << 14)) ^
+				(w[t - 15] >>> 3)
+
+			const s1 =
+				((w[t - 2] >>> 17) | (w[t - 2] << 15)) ^
+				((w[t - 2] >>> 19) | (w[t - 2] << 13)) ^
+				(w[t - 2] >>> 10)
+
+			w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0
+		}
+
+		let [a, b, c, d, e, f, g, h] = H
+		for (let t = 0; t < 64; t++) {
+			const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7))
+			const t1 = (h + S1 + ((e & f) ^ (~e & g)) + K[t] + w[t]) >>> 0
+			const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10))
+			const t2 = (S0 + ((a & b) ^ (a & c) ^ (b & c))) >>> 0
+			h = g
+			g = f
+			f = e
+			e = (d + t1) >>> 0
+			d = c
+			c = b
+			b = a
+			a = (t1 + t2) >>> 0
+		}
+
+		H[0] = (H[0] + a) >>> 0
+		H[1] = (H[1] + b) >>> 0
+		H[2] = (H[2] + c) >>> 0
+		H[3] = (H[3] + d) >>> 0
+		H[4] = (H[4] + e) >>> 0
+		H[5] = (H[5] + f) >>> 0
+		H[6] = (H[6] + g) >>> 0
+		H[7] = (H[7] + h) >>> 0
+	}
+
+	const digest = new Uint8Array(32)
+	const out = new DataView(digest.buffer)
+	for (let i = 0; i < 8; i++) {
+		out.setUint32(i * 4, H[i])
+	}
+
+	return digest
+}
+
+/** Hex SHA-256 of a UTF-8 string — e.g. the Apple request nonce binding. */
+export function sha256Hex(input: string): string {
+	return [...sha256(utf8Bytes(input))].map((x) => x.toString(16).padStart(2, '0')).join('')
+}