@tempoxyz/auth 0.0.0-pr-19.sha-2c8fa8e → 0.0.0-pr-22.sha-291bbcb

package/dist/actions/redirect.d.ts

@@ -0,0 +1,84 @@
+import { type AccessKey, type Auth, type Authorization, type Pending } from '../Auth.ts';
+/**
+ * Finishes a {@link start} when the page loads with Tempo Auth's callback, and returns `undefined`
+ * otherwise. The code is redeemed once, however often the page calls this.
+ *
+ * @example
+ * ```ts
+ * const authorization =
+ *   (await Actions.redirect.complete(auth)) ??
+ *   (await Actions.authorize(auth, { accessKey }))
+ * ```
+ */
+export declare function complete(auth: Auth): Promise<complete.ReturnType>;
+export declare namespace complete {
+    /** The authorization, or `undefined` when the page is not a redirect's callback. */
+    type ReturnType = Authorization | undefined;
+}
+/**
+ * Returns the URL that signs the user in on Tempo Auth's pages and redirects back with a code,
+ * and the {@link Pending} state to keep until then, such as in a sealed cookie.
+ * {@link handleCallback} redeems the code for the tokens and the key authorization.
+ *
+ * @example
+ * ```ts
+ * const { pending, url } = await Actions.redirect.createUrl(auth, {
+ *   accessKey,
+ *   redirectUri: 'https://app.example/auth/callback',
+ * })
+ * await seal(c, 'oauth', pending)
+ * return c.redirect(url)
+ * ```
+ */
+export declare function createUrl(auth: Auth, options: createUrl.Options): Promise<createUrl.ReturnType>;
+export declare namespace createUrl {
+    type Options = {
+        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
+        accessKey: AccessKey;
+        /** Where Tempo Auth redirects back to. Defaults to the instance's `redirectUri`. */
+        redirectUri?: string | undefined;
+    };
+    type ReturnType = {
+        /** What to keep until the callback, such as in a sealed cookie. */
+        pending: Pending;
+        /** Where to send the browser. */
+        url: string;
+    };
+}
+/**
+ * Finishes a sign-in redirect: checks its state, and redeems the code with the PKCE verifier (and
+ * the client secret, for a backend) for the tokens and the key authorization.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.redirect.handleCallback(auth, {
+ *   pending: await unseal(c, 'oauth'),
+ *   url: c.req.url,
+ * })
+ * ```
+ */
+export declare function handleCallback(auth: Auth, options: handleCallback.Options): Promise<Authorization>;
+export declare namespace handleCallback {
+    type Options = {
+        /** What `createUrl` returned to keep. */
+        pending: Pending;
+        /** The callback URL Tempo Auth redirected to. */
+        url: string | URL;
+    };
+}
+/**
+ * Sends the browser to Tempo Auth's pages to sign in, keeping the redirect's state in `storage`.
+ * {@link complete} finishes it when the browser returns.
+ *
+ * @example
+ * ```ts
+ * await Actions.redirect.start(auth, { accessKey })
+ * ```
+ */
+export declare function start(auth: Auth, options: start.Options): Promise<void>;
+export declare namespace start {
+    type Options = {
+        /** What the app's key may do. Tempo Auth's pages show it, and the user approves it. */
+        accessKey: AccessKey;
+    };
+}

package/dist/actions/redirect.js

@@ -0,0 +1,142 @@
+/**
+ * Signs the user in on Tempo Auth's pages, which redirect back with a code. `start` and `complete`
+ * keep the redirect's state in `storage` for a browser app. `createUrl` and `handleCallback` hand
+ * it to the app to keep, for a backend or a native app.
+ * @module
+ */
+import { Base64, Bytes, Hash } from 'ox';
+import { Secp256k1 } from 'viem/tempo';
+import { RequestError, } from '../Auth.js';
+import * as Api from '../internal/api.js';
+import { request } from '../internal/request.js';
+/**
+ * Finishes a {@link start} when the page loads with Tempo Auth's callback, and returns `undefined`
+ * otherwise. The code is redeemed once, however often the page calls this.
+ *
+ * @example
+ * ```ts
+ * const authorization =
+ *   (await Actions.redirect.complete(auth)) ??
+ *   (await Actions.authorize(auth, { accessKey }))
+ * ```
+ */
+export function complete(auth) {
+    completed ??= (async () => {
+        const stored = storage(auth).getItem(storageKey);
+        storage(auth).removeItem(storageKey);
+        const url = new URL(window.location.href);
+        if (!url.searchParams.has('code'))
+            return undefined;
+        // The app keeps its own query and fragment, without the callback's parameters. A code this page
+        // did not request is dropped too, since it redeems for whoever crafted its request.
+        const clean = new URL(url);
+        for (const name of ['code', 'state'])
+            clean.searchParams.delete(name);
+        window.history.replaceState(null, '', clean.pathname + clean.search + clean.hash);
+        if (!stored)
+            return undefined;
+        return handleCallback(auth, { pending: JSON.parse(stored), url });
+    })();
+    return completed;
+}
+/**
+ * Returns the URL that signs the user in on Tempo Auth's pages and redirects back with a code,
+ * and the {@link Pending} state to keep until then, such as in a sealed cookie.
+ * {@link handleCallback} redeems the code for the tokens and the key authorization.
+ *
+ * @example
+ * ```ts
+ * const { pending, url } = await Actions.redirect.createUrl(auth, {
+ *   accessKey,
+ *   redirectUri: 'https://app.example/auth/callback',
+ * })
+ * await seal(c, 'oauth', pending)
+ * return c.redirect(url)
+ * ```
+ */
+export async function createUrl(auth, options) {
+    const redirectUri = options.redirectUri ?? auth.redirectUri ?? `${window.location.origin}/`;
+    const pending = {
+        privateKey: Secp256k1.randomPrivateKey(),
+        redirectUri,
+        // `Bytes.random` needs only `crypto.getRandomValues`, which React Native polyfills.
+        state: Base64.fromBytes(Bytes.random(16), base64url),
+        verifier: Base64.fromBytes(Bytes.random(32), base64url),
+    };
+    const { client_id, keyAuthorization, scope } = request(auth, {
+        accessKey: options.accessKey,
+        privateKey: pending.privateKey,
+    });
+    const url = new URL('/authorize', auth.url);
+    url.search = new URLSearchParams({
+        client_id,
+        code_challenge: Base64.fromBytes(Hash.sha256(Bytes.fromString(pending.verifier)), base64url),
+        key_authorization: Base64.fromString(JSON.stringify(keyAuthorization), base64url),
+        redirect_uri: redirectUri,
+        scope,
+        state: pending.state,
+    }).toString();
+    return { pending, url: url.href };
+}
+/**
+ * Finishes a sign-in redirect: checks its state, and redeems the code with the PKCE verifier (and
+ * the client secret, for a backend) for the tokens and the key authorization.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.redirect.handleCallback(auth, {
+ *   pending: await unseal(c, 'oauth'),
+ *   url: c.req.url,
+ * })
+ * ```
+ */
+export async function handleCallback(auth, options) {
+    const { pending } = options;
+    const params = new URL(options.url).searchParams;
+    const code = params.get('code');
+    if (!code || params.get('state') !== pending.state)
+        throw new RequestError({
+            message: 'Sign-in failed. Start again.',
+            status: 400,
+        });
+    const body = await Api.token(auth, {
+        code,
+        code_verifier: pending.verifier,
+        grant_type: 'authorization_code',
+        redirect_uri: pending.redirectUri,
+    });
+    if (!body.account || !body.key_authorization)
+        throw new RequestError({
+            message: 'Sign-in failed. Start again.',
+            status: 400,
+        });
+    return Api.authorization({
+        account: body.account,
+        keyAuthorization: body.key_authorization,
+        tokens: body,
+    }, pending);
+}
+/**
+ * Sends the browser to Tempo Auth's pages to sign in, keeping the redirect's state in `storage`.
+ * {@link complete} finishes it when the browser returns.
+ *
+ * @example
+ * ```ts
+ * await Actions.redirect.start(auth, { accessKey })
+ * ```
+ */
+export async function start(auth, options) {
+    const { pending, url } = await createUrl(auth, options);
+    storage(auth).setItem(storageKey, JSON.stringify(pending));
+    window.location.assign(url);
+}
+/** Unpadded URL-safe Base64, as PKCE and `key_authorization` use. */
+const base64url = { pad: false, url: true };
+/** The redirect this page load returns from, so its code is redeemed once. */
+let completed;
+/** Where a redirect keeps its state in `storage`. */
+const storageKey = 'tempo-auth:redirect';
+/** Where a redirect keeps its state: the instance's `storage`, or the page's session storage. */
+function storage(auth) {
+    return auth.storage ?? sessionStorage;
+}

package/dist/actions/tempoAccount.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Manages the signed-in user's Tempo Accounts.
+ * @module
+ */
+import type { Auth, TempoAccount } from '../Auth.ts';
+/**
+ * Creates another Tempo Account for the signed-in user, and returns it. Pass its `address` as an
+ * access key's `account` to authorize keys on it.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = await Actions.tempoAccount.create(auth)
+ * await Actions.authorize(auth, {
+ *   accessKey: { ...accessKey, account: tempoAccount.address },
+ * })
+ * ```
+ */
+export declare function create(auth: Auth): Promise<create.ReturnType>;
+export declare namespace create {
+    /** The new account. */
+    type ReturnType = TempoAccount;
+}
+/**
+ * Lists the signed-in user's Tempo Accounts, their default first.
+ *
+ * @example
+ * ```ts
+ * const [account, ...others] = await Actions.tempoAccount.list(auth)
+ * ```
+ */
+export declare function list(auth: Auth): Promise<list.ReturnType>;
+export declare namespace list {
+    /** The user's accounts, their default first. */
+    type ReturnType = readonly TempoAccount[];
+}

package/dist/actions/tempoAccount.js

@@ -0,0 +1,31 @@
+import * as Api from '../internal/api.js';
+/**
+ * Creates another Tempo Account for the signed-in user, and returns it. Pass its `address` as an
+ * access key's `account` to authorize keys on it.
+ *
+ * @example
+ * ```ts
+ * const tempoAccount = await Actions.tempoAccount.create(auth)
+ * await Actions.authorize(auth, {
+ *   accessKey: { ...accessKey, account: tempoAccount.address },
+ * })
+ * ```
+ */
+export async function create(auth) {
+    const { address } = await Api.json(await Api.post(auth, '/api/account/tempo', { json: {} }));
+    return { address };
+}
+/**
+ * Lists the signed-in user's Tempo Accounts, their default first.
+ *
+ * @example
+ * ```ts
+ * const [account, ...others] = await Actions.tempoAccount.list(auth)
+ * ```
+ */
+export async function list(auth) {
+    const { tempo } = await Api.json(await (auth.fetch ?? fetch)(new URL('/api/account', auth.url), {
+        credentials: 'include',
+    }));
+    return tempo.map(({ address }) => ({ address }));
+}

package/dist/internal/api.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Calls Tempo Auth's API, and reads its responses into what the actions return.
+ * @module
+ */
+import { type Hex } from 'ox';
+import type { KeyAuthorization } from 'ox/tempo';
+import { type Auth, type Authorization, type Tokens } from '../Auth.ts';
+import * as Key from '../Key.ts';
+/** Builds an authorization from what Tempo Auth returned and the key the app generated. */
+export declare function authorization(body: Headless, options: {
+    privateKey: Hex.Hex;
+}): Authorization;
+/** What the headless API returns for an authorization. */
+export type Headless = {
+    account: Key.Key['account'];
+    keyAuthorization: KeyAuthorization.Rpc;
+    tokens: TokenResponse | Tokens;
+};
+/** Reads a JSON response, and throws a {@link RequestError} for a refused request. */
+export declare function json<value = unknown>(response: Response): Promise<value>;
+/** Posts JSON to Tempo Auth's API with the session cookie. */
+export declare function post(auth: Auth, path: string, options: {
+    json?: unknown;
+}): Promise<Response>;
+/**
+ * Calls Tempo Auth's OAuth token endpoint, adding the client and any secret. It forwards standard
+ * OAuth form posts to WorkOS.
+ */
+export declare function token(auth: Auth, body: Record<string, string>): Promise<TokenResponse>;
+/** What Tempo Auth's token endpoint returns. Redeeming a redirect's code adds its key authorization. */
+export type TokenResponse = {
+    access_token: string;
+    account?: Key.Key['account'] | undefined;
+    expires_in: number;
+    id_token?: string | undefined;
+    key_authorization?: KeyAuthorization.Rpc | undefined;
+    refresh_token?: string | undefined;
+};
+/** Reads a token response into `Tokens`. */
+export declare function tokens(response: TokenResponse): Tokens;

package/dist/internal/api.js

@@ -0,0 +1,70 @@
+/**
+ * Calls Tempo Auth's API, and reads its responses into what the actions return.
+ * @module
+ */
+import { Base64 } from 'ox';
+import { RequestError, } from '../Auth.js';
+import * as Key from '../Key.js';
+/** Builds an authorization from what Tempo Auth returned and the key the app generated. */
+export function authorization(body, options) {
+    const key = {
+        account: body.account,
+        keyAuthorization: body.keyAuthorization,
+        privateKey: options.privateKey,
+    };
+    const tokens_ = 'accessToken' in body.tokens ? body.tokens : tokens(body.tokens);
+    const claims = JSON.parse(Base64.toString(tokens_.idToken.split('.')[1]));
+    return {
+        ...tokens_,
+        account: Key.toAccount(key),
+        key,
+        user: { email: claims.email, id: claims.sub },
+    };
+}
+/** Reads a JSON response, and throws a {@link RequestError} for a refused request. */
+export async function json(response) {
+    // Some refusals, such as the CSRF check's, answer plain text.
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        throw new RequestError({
+            message: body.error ?? 'Something went wrong.',
+            status: response.status,
+        });
+    return body;
+}
+/** Posts JSON to Tempo Auth's API with the session cookie. */
+export function post(auth, path, options) {
+    return (auth.fetch ?? fetch)(new URL(path, auth.url), {
+        ...(options.json === undefined
+            ? {}
+            : {
+                body: JSON.stringify(options.json),
+                headers: { 'content-type': 'application/json' },
+            }),
+        credentials: 'include',
+        method: 'POST',
+    });
+}
+/**
+ * Calls Tempo Auth's OAuth token endpoint, adding the client and any secret. It forwards standard
+ * OAuth form posts to WorkOS.
+ */
+export async function token(auth, body) {
+    return json(await (auth.fetch ?? fetch)(new URL('/oauth2/token', auth.url), {
+        body: new URLSearchParams({
+            ...body,
+            client_id: auth.clientId,
+            ...(auth.clientSecret ? { client_secret: auth.clientSecret } : {}),
+        }),
+        method: 'POST',
+    }));
+}
+/** Reads a token response into `Tokens`. */
+export function tokens(response) {
+    return {
+        accessToken: response.access_token,
+        expiresAt: Date.now() + response.expires_in * 1000,
+        idToken: response.id_token,
+        refreshToken: response.refresh_token,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempoxyz/auth",
-  "version": "0.0.0-pr-19.sha-2c8fa8e",
+  "version": "0.0.0-pr-22.sha-291bbcb",
   "description": "Signs users in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
   "type": "module",
   "exports": {