@octane-xplat/auth 0.9.0 → 0.11.0

package/README.md

@@ -1,24 +1,28 @@
 # `@octane-xplat/auth`
 
-Sign in with Apple and Google Sign-In for Octane xplat apps — the native
-SDKs (`@nativescript/apple-sign-in`, `@nativescript/google-signin`) on
-iOS/Android, the providers' web SDKs (Apple JS / Google Identity Services)
-in the browser, and AuthenticationServices through the ObjC bridge plus a
-Google flow on the macOS AppKit host. One `AuthUser`/`AuthCredential`
-contract everywhere.
-
 ```sh
 pnpm add @octane-xplat/auth
 ```
 
-```tsx
-import { appleAuth, googleAuth, AppleSignInButton } from '@octane-xplat/auth'
+Sign in with Apple and Google Sign-In for Octane xplat apps — the native
+SDKs (`@nativescript/apple-sign-in`, `@nativescript/google-signin`) on
+iOS/Android, the providers' web SDKs (Apple JS / Google Identity Services)
+in the browser, and AuthenticationServices through the ObjC bridge plus a
+app-configured hosted Google flow on the macOS AppKit host. One `AuthUser`/`AuthCredential`
+contract everywhere. `createHostedAuth` adds a generic hosted sign-in
+ceremony + Bearer session transport for apps whose backend issues and redeems
+sign-in attempts.
 
-appleAuth.configure({ clientId: 'com.example.app.web' }) // web-only fields
+```ts
+import { appleAuth } from '@octane-xplat/auth'
 
-const result = await appleAuth.signIn({ scopes: ['email', 'name'] })
-if (result.status === 'success') {
-	const { idToken, user } = result.credential // hand idToken to your backend
+appleAuth.configure({ clientId: 'com.example.app.web' })
+if (appleAuth.supported) {
+	const result = await appleAuth.signIn({ scopes: ['email', 'name'] })
+	if (result.status === 'success') {
+		// Send this credential to your backend for verification.
+		const { idToken, user } = result.credential
+	}
 }
 ```
 
@@ -26,13 +30,108 @@ Each provider object reports `supported` — Apple is `false` on Android —
 and exposes `configure`, `signIn`, and provider extras
 (`appleAuth.getCredentialState`, `googleAuth.signOut`). `SignInResult`
 distinguishes `success` / `cancelled` / `error`; a dismissed sheet is
-`cancelled`, not a throw. The sign-in buttons are platform-authentic
-components, so render them from platform-suffixed files or accept each
+`cancelled`, not a throw. Apple uses the official ASAuthorizationAppleIDButton on AppKit; Google
+uses a text trigger for the hosted flow there. The other sign-in buttons are
+platform-authentic components, so render them from platform-suffixed files or accept each
 target's native styling.
 
+The following component belongs in an `.ios.tsx` file.
+
+```tsx
+import { AppleSignInButton, appleAuth, googleAuth } from '@octane-xplat/auth'
+
+export function SignIn() {
+	return (
+		<AppleSignInButton
+			onResult={(result) => {
+				if (result.status === 'success') {
+					void appleAuth.getCredentialState(result.credential.user.id)
+				}
+			}}
+		/>
+	)
+}
+// When ending a Google session:
+await googleAuth.signOut()
+```
+
 Web needs registered client IDs; iOS needs the `applesignin` entitlement
 and Google's `GoogleService-Info.plist`/reversed-client-id URL scheme;
 Android needs `google-services.json` and a `serverClientId` for
 `serverAuthCode`. Guide: [Using device
-features](../../docs/platform-services.md). Exercised by
+features](../../docs/platform/platform-services.md). Exercised by
 [`AuthDemo`](../demos/src/AuthDemo.tsrx).
+
+On macOS, `supported` reports AuthenticationServices availability, not completed
+provider registration. Apple needs a signed app ID with Sign in with Apple
+enabled and a matching provisioning profile and entitlement. Google needs
+`googleAuth.configure({ hostedFlow })`, where `createRequest` starts a fresh
+backend attempt and `complete` validates/redeems the captured callback on that
+backend, returning `AuthCredential`. A client ID alone is insufficient on
+AppKit. The adapter receives the configured client IDs, scopes, hosted domain,
+and per-attempt nonce; the backend must apply and verify them.
+
+See [macOS provider setup](../../docs/platform/platform-services.md#macos-provider-sign-in)
+and the [maintained hosted adapter](../../examples/auth/google-hosted.macos.ts).
+
+## Hosted sign-in ceremonies
+
+`createHostedAuth` authenticates a native app through a hosted sign-in page:
+your `HostedAuthFlow` issues a PKCE-bound attempt and returns the hosted URL,
+the app opens it in a system browser (`authSession` — ASWebAuthenticationSession
+on iOS/macOS, Custom Tab on Android), and `complete` redeems the browser
+callback. The client persists the credential record — a short-lived access
+token plus a durable session credential — through
+`@octane-xplat/secure-storage` (Keychain/Keystore), refreshes the access token
+through the flow's `refresh`, and revokes through `revoke` on sign-out.
+
+```ts
+import { createHostedAuth, postJson, queryParam } from '@octane-xplat/auth'
+
+export const auth = createHostedAuth({
+	apiOrigin: 'https://api.example.com',
+	flow: {
+		async begin({ fetch, pkce }) {
+			const res = await postJson(fetch, 'https://api.example.com/oauth/attempt', {
+				code_challenge: pkce.challenge,
+				scheme: 'myapp',
+			})
+			if (!res.ok) throw new Error(`attempt rejected (${res.status})`)
+			const { attempt_id, state } = await res.json()
+			return {
+				url: `https://api.example.com/sign-in?attempt=${attempt_id}&state=${state}`,
+				callbackScheme: 'myapp',
+				state,
+			}
+		},
+		async complete(callbackUrl, attempt, { fetch, pkce }) {
+			const res = await postJson(fetch, 'https://api.example.com/oauth/exchange', {
+				code: queryParam(callbackUrl, 'code'),
+				code_verifier: pkce.verifier,
+				state: attempt.state,
+			})
+			if (!res.ok) return null
+			const { token, expires_at, session_token } = await res.json()
+			return { expiresAt: expires_at * 1000, sessionToken: session_token, token }
+		},
+	},
+})
+
+const result = await auth.signIn() // opens the hosted sign-in page
+if (result.status === 'success') {
+	const response = await auth.fetch('/api/me') // Bearer attach + refresh-on-401
+}
+```
+
+`auth.fetch` attaches `Authorization: Bearer <access token>` to same-origin
+`/api/*` paths (the `/api/auth` mount is excluded by default — override
+`authorizePath` for other layouts) and replays once after a refresh when the
+server answers an `invalid_token` challenge. The `callbackScheme` your flow
+returns must be registered as an incoming-link scheme in the app (Android: a
+manifest intent-filter) and allowlisted by your backend. On web `supported` is
+`false` — browser apps keep the cookie session flow.
+
+```ts
+const status = await auth.restore() // 'authenticated' if a session was stored
+await auth.signOut() // revokes the session and clears stored credentials
+```

package/dist/native/auth/src/base64.js

@@ -0,0 +1,17 @@
+//#region src/base64.ts
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+function bytesToBase64Url(bytes) {
+	let out = "";
+	for (let i = 0; i < bytes.length; i += 3) {
+		const a = bytes[i];
+		const b = i + 1 < bytes.length ? bytes[i + 1] : 0;
+		const c = i + 2 < bytes.length ? bytes[i + 2] : 0;
+		out += ALPHABET[a >> 2];
+		out += ALPHABET[(a & 3) << 4 | b >> 4];
+		if (i + 1 < bytes.length) out += ALPHABET[(b & 15) << 2 | c >> 6];
+		if (i + 2 < bytes.length) out += ALPHABET[c & 63];
+	}
+	return out;
+}
+//#endregion
+export { bytesToBase64Url };

package/dist/native/auth/src/hosted.js

@@ -0,0 +1,252 @@
+import { random } from "../../platform/src/random.js";
+import { authSession } from "../../platform/src/auth-session.js";
+import "../../platform/src/index.js";
+import { secureStorage } from "../../secure-storage/src/secure-storage.js";
+import "../../secure-storage/src/index.js";
+import { bytesToBase64Url } from "./base64.js";
+import { sha256, utf8Bytes } from "./sha256.js";
+//#region src/hosted.ts
+var DEFAULT_STORAGE_KEY = "hosted-auth";
+var REFRESH_SKEW_MS = 3e4;
+function createHostedAuth(config) {
+	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 = config.fetch ?? ((url, init) => {
+		const impl = globalThis.fetch;
+		if (!impl) return Promise.reject(/* @__PURE__ */ new Error("hostedAuth: fetch is unavailable on this target"));
+		return impl(url, init);
+	});
+	let credentials;
+	let refreshPromise = null;
+	function store() {
+		return config.storage ?? secureStorage.impl;
+	}
+	async function persist(creds) {
+		credentials = creds;
+		const storage = store();
+		if (!storage) return;
+		try {
+			if (creds) await storage.set(storageKey, JSON.stringify(creds));
+			else await storage.remove(storageKey);
+		} catch {}
+	}
+	async function load() {
+		if (credentials !== void 0) return credentials;
+		const storage = store();
+		if (!storage) {
+			credentials = null;
+			return null;
+		}
+		try {
+			const raw = await storage.get(storageKey);
+			const parsed = raw ? parseCredentials(raw) : null;
+			if (credentials === void 0) credentials = parsed;
+			if (!parsed && raw) await storage.remove(storageKey);
+		} catch {
+			credentials ??= null;
+		}
+		return credentials ?? null;
+	}
+	async function refresh() {
+		const creds = await load();
+		if (!creds || !config.flow.refresh) return null;
+		const next = await config.flow.refresh(creds, { fetch: transport });
+		if (!isCredentials(next)) {
+			await persist(null);
+			return null;
+		}
+		await persist(next);
+		return next.token;
+	}
+	function refreshedAccessToken() {
+		refreshPromise ??= refresh().finally(() => {
+			refreshPromise = null;
+		});
+		return refreshPromise;
+	}
+	async function getAccessToken() {
+		const creds = await load();
+		if (!creds) return null;
+		if (creds.expiresAt - now() > REFRESH_SKEW_MS) return creds.token;
+		return refreshedAccessToken();
+	}
+	async function signIn() {
+		const session = config.authSession ?? {
+			supported: authSession.supported,
+			open: (url, options) => {
+				const impl = authSession.impl;
+				if (!impl) return Promise.resolve({
+					type: "error",
+					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;
+		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 !== void 0 && 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, init) {
+		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 {}
+	}
+	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) {
+	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. */
+function postJson(transport, url, body) {
+	return transport(url, {
+		body: JSON.stringify(body),
+		headers: { "content-type": "application/json" },
+		method: "POST"
+	});
+}
+/** `?name=value` extraction without URLSearchParams (not in the native program). */
+function queryParam(url, name) {
+	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("=");
+		if ((eq === -1 ? pair : pair.slice(0, eq)) === name) return eq === -1 ? "" : decodeURIComponent(pair.slice(eq + 1).replaceAll("+", " "));
+	}
+	return null;
+}
+function isCredentials(value) {
+	const creds = value;
+	return !!creds && typeof creds.token === "string" && typeof creds.expiresAt === "number" && typeof creds.sessionToken === "string";
+}
+function parseCredentials(raw) {
+	try {
+		const parsed = JSON.parse(raw);
+		if (isCredentials(parsed)) return {
+			expiresAt: parsed.expiresAt,
+			sessionToken: parsed.sessionToken,
+			token: parsed.token
+		};
+	} catch {}
+	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, apiOrigin) {
+	if (url.startsWith("//")) return null;
+	let path;
+	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) {
+	return pathname.startsWith("/api/") && !(pathname === "/api/auth" || pathname.startsWith("/api/auth/"));
+}
+function withBearer(init, token) {
+	const headers = {};
+	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, headers) {
+	if (status !== 401) return false;
+	const challenge = headers.get("www-authenticate");
+	return !!challenge && /error\s*=\s*"invalid_token"/iu.test(challenge);
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : "hostedAuth: the hosted ceremony failed";
+}
+//#endregion
+export { createHostedAuth, postJson, queryParam };

package/dist/native/auth/src/sha256.js

@@ -0,0 +1,141 @@
+//#region src/sha256.ts
+function utf8Bytes(input) {
+	const bytes = [];
+	for (let i = 0; i < input.length; i++) {
+		let cp = input.charCodeAt(i);
+		if (cp >= 55296 && cp <= 56319 && i + 1 < input.length) {
+			const low = input.charCodeAt(i + 1);
+			if (low >= 56320 && low <= 57343) {
+				cp = 65536 + (cp - 55296 << 10) + (low - 56320);
+				i++;
+			}
+		}
+		if (cp < 128) bytes.push(cp);
+		else if (cp < 2048) bytes.push(192 | cp >> 6, 128 | cp & 63);
+		else if (cp < 65536) bytes.push(224 | cp >> 12, 128 | cp >> 6 & 63, 128 | cp & 63);
+		else bytes.push(240 | cp >> 18, 128 | cp >> 12 & 63, 128 | cp >> 6 & 63, 128 | cp & 63);
+	}
+	return new Uint8Array(bytes);
+}
+function sha256(bytes) {
+	const K = new Uint32Array([
+		1116352408,
+		1899447441,
+		3049323471,
+		3921009573,
+		961987163,
+		1508970993,
+		2453635748,
+		2870763221,
+		3624381080,
+		310598401,
+		607225278,
+		1426881987,
+		1925078388,
+		2162078206,
+		2614888103,
+		3248222580,
+		3835390401,
+		4022224774,
+		264347078,
+		604807628,
+		770255983,
+		1249150122,
+		1555081692,
+		1996064986,
+		2554220882,
+		2821834349,
+		2952996808,
+		3210313671,
+		3336571891,
+		3584528711,
+		113926993,
+		338241895,
+		666307205,
+		773529912,
+		1294757372,
+		1396182291,
+		1695183700,
+		1986661051,
+		2177026350,
+		2456956037,
+		2730485921,
+		2820302411,
+		3259730800,
+		3345764771,
+		3516065817,
+		3600352804,
+		4094571909,
+		275423344,
+		430227734,
+		506948616,
+		659060556,
+		883997877,
+		958139571,
+		1322822218,
+		1537002063,
+		1747873779,
+		1955562222,
+		2024104815,
+		2227730452,
+		2361852424,
+		2428436474,
+		2756734187,
+		3204031479,
+		3329325298
+	]);
+	const H = new Uint32Array([
+		1779033703,
+		3144134277,
+		1013904242,
+		2773480762,
+		1359893119,
+		2600822924,
+		528734635,
+		1541459225
+	]);
+	const bitLen = bytes.length * 8;
+	const padded = new Uint8Array(bytes.length + 9 + 63 & -64);
+	padded.set(bytes);
+	padded[bytes.length] = 128;
+	const dv = new DataView(padded.buffer);
+	dv.setUint32(padded.length - 8, Math.floor(bitLen / 4294967296));
+	dv.setUint32(padded.length - 4, bitLen >>> 0);
+	const w = /* @__PURE__ */ 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 t2 = ((a >>> 2 | a << 30) ^ (a >>> 13 | a << 19) ^ (a >>> 22 | a << 10)) + (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 = /* @__PURE__ */ new Uint8Array(32);
+	const out = new DataView(digest.buffer);
+	for (let i = 0; i < 8; i++) out.setUint32(i * 4, H[i]);
+	return digest;
+}
+//#endregion
+export { sha256, utf8Bytes };

package/dist/native/index.js

@@ -1,5 +1,6 @@
-import { appleAuth } from "./apple.js";
-import { googleAuth } from "./google.js";
-import { AppleSignInButton } from "./AppleSignInButton.tsrx.js";
-import { GoogleSignInButton } from "./GoogleSignInButton.tsrx.js";
-export { AppleSignInButton, GoogleSignInButton, appleAuth, googleAuth };
+import { appleAuth } from "./auth/src/apple.js";
+import { googleAuth } from "./auth/src/google.js";
+import { AppleSignInButton } from "./auth/src/AppleSignInButton.tsrx.js";
+import { GoogleSignInButton } from "./auth/src/GoogleSignInButton.tsrx.js";
+import { createHostedAuth, postJson, queryParam } from "./auth/src/hosted.js";
+export { AppleSignInButton, GoogleSignInButton, appleAuth, createHostedAuth, googleAuth, postJson, queryParam };

package/dist/native/octane-client-build.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "buildId": "2924c745-ebe0-4012-9aea-c8c26eeb7458",
+  "buildId": "bb35374e-9484-4dd6-88c4-77050251d038",
   "mode": "production",
   "capabilities": {
     "independentHydration": false

package/dist/native/platform/src/a11y.js

@@ -0,0 +1 @@
+import "@nativescript/core";

package/dist/native/platform/src/app-info.js

@@ -0,0 +1 @@
+import "@nativescript/core";