@voltro/plugin-auth 0.80.0 → 0.82.0

package/dist/native.d.ts

@@ -0,0 +1,105 @@
+import { Subject } from '@voltro/protocol';
+
+/**
+ * Mint the verifier + state and build the authorize URL. Nothing is sent yet;
+ * the app opens `url` and waits for its redirect URI to be hit.
+ */
+export declare const beginNativeLogin: (options: NativeLoginOptions) => Promise<NativeLoginHandoff>;
+
+/** Trade the code + verifier for the session value. */
+export declare const exchangeNativeCode: (input: {
+    readonly code: string;
+    readonly codeVerifier: string;
+}, options: Pick<NativeLoginOptions, "apiBaseUrl" | "prefix"> & {
+    readonly fetch?: typeof fetch;
+}) => Promise<NativeSession>;
+
+export declare type NativeCallback = {
+    readonly kind: 'code';
+    readonly code: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+} | {
+    readonly kind: 'ignored';
+    readonly reason: 'not-the-callback' | 'state-mismatch' | 'no-code';
+};
+
+/** RFC 7636 S256 challenge for a verifier, through the injected hash. */
+export declare const nativeCodeChallenge: (verifier: string, crypto: NativeCrypto) => Promise<string>;
+
+/** The platform's entropy and hash. `randomBytes(n)` must be a CSPRNG. */
+export declare interface NativeCrypto {
+    readonly randomBytes: (length: number) => Uint8Array;
+    readonly sha256: (bytes: Uint8Array) => Promise<Uint8Array>;
+}
+
+export declare class NativeExchangeError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string);
+}
+
+export declare interface NativeLoginHandoff {
+    /** Open this in the SYSTEM browser (not an in-app webview): the user's
+     *  existing browser session and password manager are the point. */
+    readonly url: string;
+    /** Keep both until the callback arrives — they are what makes the code
+     *  usable by this app and this attempt only. */
+    readonly codeVerifier: string;
+    readonly state: string;
+}
+
+export declare interface NativeLoginOptions {
+    /** The api origin the `/auth/*` routes live on (`https://api.example.com`),
+     *  or the web origin that proxies them. No trailing slash needed. */
+    readonly apiBaseUrl: string;
+    /** The URL the app listens on, byte for byte one of the plugin's
+     *  `native.redirectUris`. */
+    readonly redirectUri: string;
+    readonly crypto: NativeCrypto;
+    /** The auth routes' prefix. Default `/auth`. */
+    readonly prefix?: string;
+}
+
+export declare interface NativeLoginRunner extends NativeLoginOptions {
+    /** Open the authorize URL in the system browser. */
+    readonly open: (url: string) => void | Promise<void>;
+    /** Resolve with the callback URL the OS hands the app (the first one that
+     *  is this login's; see `parseNativeCallback`). */
+    readonly awaitCallback: (isOurs: (url: string) => NativeCallback) => Promise<NativeCallback>;
+    readonly fetch?: typeof fetch;
+}
+
+export declare interface NativeSession {
+    /** Present this on `x-voltro-session` — see {@link sessionHeaders}. */
+    readonly session: string;
+    /** Unix seconds the session expires. Probe `GET /auth/session` before then
+     *  to receive a renewed value. */
+    readonly expiresAt: number;
+    readonly subject: Subject;
+}
+
+/**
+ * Read the callback the system browser sent the app to. `state` must match
+ * the handoff's; an unrelated URL (the app's ordinary deep links pass through
+ * the same listener) is `ignored`.
+ */
+export declare const parseNativeCallback: (url: string, handoff: Pick<NativeLoginHandoff, "state">, redirectUri: string) => NativeCallback;
+
+/**
+ * Probe `GET /auth/session` with a header-presented value. Answers the
+ * renewed value when the server rotated it, the same value otherwise, or
+ * `null` when the session no longer authenticates (sign the user in again).
+ */
+export declare const probeNativeSession: (session: string, options: Pick<NativeLoginOptions, "apiBaseUrl" | "prefix"> & {
+    readonly fetch?: typeof fetch;
+}) => Promise<NativeSession | null>;
+
+/** One call: open the browser, wait for the callback, exchange the code. */
+export declare const runNativeLogin: (runner: NativeLoginRunner) => Promise<NativeSession>;
+
+/** The rpc headers for a session value — hand to `ResolvableHeaders`. */
+export declare const sessionHeaders: (session: string) => Readonly<Record<string, string>>;
+
+export { }

package/dist/native.js

@@ -0,0 +1,93 @@
+import { SESSION_HEADER_NAME as e } from "@voltro/protocol";
+//#region src/native/index.ts
+var t = (e) => {
+	let t = "";
+	for (let n of e) t += String.fromCharCode(n);
+	return (typeof btoa == "function" ? btoa(t) : globalThis.Buffer.from(t, "binary").toString("base64")).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}, n = (e) => {
+	let t = new Uint8Array(e.length);
+	for (let n = 0; n < e.length; n++) t[n] = e.charCodeAt(n) & 127;
+	return t;
+}, r = (e) => e.replace(/\/+$/, ""), i = async (e, r) => t(await r.sha256(n(e))), a = async (e) => {
+	let n = t(e.crypto.randomBytes(32)), a = t(e.crypto.randomBytes(16)), o = await i(n, e.crypto), s = new URLSearchParams({
+		redirect_uri: e.redirectUri,
+		code_challenge: o,
+		code_challenge_method: "S256",
+		state: a
+	}), c = e.prefix ?? "/auth";
+	return {
+		url: `${r(e.apiBaseUrl)}${c}/native/authorize?${s.toString()}`,
+		codeVerifier: n,
+		state: a
+	};
+}, o = (e, t, n) => {
+	let i = e.indexOf("?");
+	if (r(i === -1 ? e : e.slice(0, i)) !== r(n)) return {
+		kind: "ignored",
+		reason: "not-the-callback"
+	};
+	let a = new URLSearchParams(i === -1 ? "" : e.slice(i + 1));
+	if (a.get("state") !== t.state) return {
+		kind: "ignored",
+		reason: "state-mismatch"
+	};
+	let o = a.get("error");
+	if (o) return {
+		kind: "error",
+		error: o
+	};
+	let s = a.get("code");
+	return s ? {
+		kind: "code",
+		code: s
+	} : {
+		kind: "ignored",
+		reason: "no-code"
+	};
+}, s = class extends Error {
+	status;
+	code;
+	constructor(e, t) {
+		super(`native login exchange failed: ${t} (${e})`), this.name = "NativeExchangeError", this.status = e, this.code = t;
+	}
+}, c = async (e, t) => {
+	let n = t.fetch ?? fetch, i = t.prefix ?? "/auth", a = await n(`${r(t.apiBaseUrl)}${i}/native/exchange`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(e)
+	}), o = await a.json().catch(() => ({}));
+	if (!a.ok || typeof o.session != "string" || typeof o.expiresAt != "number" || !o.subject) throw new s(a.status, o.error ?? "invalid_response");
+	return {
+		session: o.session,
+		expiresAt: o.expiresAt,
+		subject: o.subject
+	};
+}, l = (t) => ({ [e]: t }), u = async (e, t) => {
+	let n = t.fetch ?? fetch, i = t.prefix ?? "/auth", a = await n(`${r(t.apiBaseUrl)}${i}/session`, {
+		method: "GET",
+		headers: l(e)
+	});
+	if (a.status === 401) return null;
+	let o = await a.json().catch(() => ({}));
+	return !a.ok || o.ok !== !0 || !o.subject || typeof o.expiresAt != "number" ? null : {
+		session: o.session ?? e,
+		expiresAt: o.expiresAt,
+		subject: o.subject
+	};
+}, d = async (e) => {
+	let t = await a(e);
+	await e.open(t.url);
+	let n = await e.awaitCallback((n) => o(n, t, e.redirectUri));
+	if (n.kind === "error") throw new s(0, n.error);
+	if (n.kind !== "code") throw new s(0, n.reason);
+	return c({
+		code: n.code,
+		codeVerifier: t.codeVerifier
+	}, {
+		apiBaseUrl: e.apiBaseUrl,
+		...e.prefix === void 0 ? {} : { prefix: e.prefix },
+		...e.fetch === void 0 ? {} : { fetch: e.fetch }
+	});
+};
+//#endregion
+export { s as NativeExchangeError, a as beginNativeLogin, c as exchangeNativeCode, i as nativeCodeChallenge, o as parseNativeCallback, u as probeNativeSession, d as runNativeLogin, l as sessionHeaders };