@tempoxyz/auth 0.0.0-pr-6.sha-17bb901

package/dist/Actions.d.ts

@@ -0,0 +1,241 @@
+import { type AccessKey, type Auth, type Authorization, type Pending, type Provider, type Step, type Tokens } from './Auth.ts';
+/**
+ * Authorizes the app for a person already signed in to Tempo Auth, from any app. Returns
+ * `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
+ * ceiling.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.authorize(auth, { accessKey })
+ * if (!authorization) showSignIn()
+ * ```
+ */
+export declare function authorize(auth: Auth, options: authorize.Options): Promise<authorize.ReturnType>;
+export declare namespace authorize {
+    type Options = {
+        /** What the app's key may do. It must fit the headless ceiling. */
+        accessKey: AccessKey;
+    };
+    /** The authorization, or `undefined` without a session. */
+    type ReturnType = Authorization | undefined;
+}
+/**
+ * Starts the device grant for a CLI: the person approves `userCode` at `verificationUri` from any
+ * browser, and `wait` resolves once they do.
+ *
+ * @example
+ * ```ts
+ * const device = await Actions.authorizeDevice(auth, { accessKey, device: Os.hostname() })
+ * console.log(`Open ${device.verificationUriComplete}`)
+ * const authorization = await device.wait()
+ * ```
+ */
+export declare function authorizeDevice(auth: Auth, options: authorizeDevice.Options): Promise<authorizeDevice.ReturnType>;
+export declare namespace authorizeDevice {
+    type Options = {
+        /** What the CLI's key may do. The approval page shows it beside the device. */
+        accessKey: AccessKey;
+        /** The name the approval page shows, such as the machine's hostname. */
+        device: string;
+    };
+    type ReturnType = {
+        /** Seconds until the code expires. */
+        expiresIn: number;
+        /** The code the person confirms in the browser. */
+        userCode: string;
+        /** Where the person enters the code. */
+        verificationUri: string;
+        /** Where the person approves the code, with it already filled in. */
+        verificationUriComplete: string;
+        /** Resolves with the authorization once the person approves. */
+        wait: () => Promise<Authorization>;
+    };
+}
+/**
+ * Returns the URL that signs the person in on Tempo Auth's pages and redirects back with a code
+ * and the key authorization, and the {@link Pending} state to keep until then, such as in a
+ * sealed cookie. {@link handleCallback} finishes it.
+ *
+ * @example
+ * ```ts
+ * const { pending, url } = await Actions.createAuthorizationUrl(auth, {
+ *   accessKey,
+ *   redirectUri: 'https://app.example/auth/callback',
+ * })
+ * await seal(c, 'oauth', pending)
+ * return c.redirect(url)
+ * ```
+ */
+export declare function createAuthorizationUrl(auth: Auth, options: createAuthorizationUrl.Options): Promise<createAuthorizationUrl.ReturnType>;
+export declare namespace createAuthorizationUrl {
+    type Options = {
+        /** What the app's key may do. Tempo Auth's pages show it, and the person 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;
+    };
+}
+/**
+ * Lists the OAuth providers Tempo Auth offers, for an app that shows its own sign-in buttons.
+ *
+ * @example
+ * ```ts
+ * const providers = await Actions.getProviders(auth)
+ * // [{ id: 'google', name: 'Google' }]
+ * ```
+ */
+export declare function getProviders(auth: Auth): Promise<getProviders.ReturnType>;
+export declare namespace getProviders {
+    type ReturnType = readonly {
+        /** The provider's short name, which `signIn` takes. */
+        id: Provider;
+        /** The name to show, such as `Google`. */
+        name: string;
+    }[];
+}
+/**
+ * Finishes a sign-in redirect: checks its state, redeems the code with the PKCE verifier (and the
+ * client secret, for a backend), and reads the key authorization from the callback URL.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.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 `createAuthorizationUrl` returned to keep. */
+        pending: Pending;
+        /** The callback URL Tempo Auth redirected to. */
+        url: string | URL;
+    };
+}
+/**
+ * Finishes a {@link redirect} 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.handleRedirect(auth)) ??
+ *   (await Actions.authorize(auth, { accessKey }))
+ * ```
+ */
+export declare function handleRedirect(auth: Auth): Promise<handleRedirect.ReturnType>;
+export declare namespace handleRedirect {
+    /** The authorization, or `undefined` when the page is not a redirect's callback. */
+    type ReturnType = Authorization | undefined;
+}
+/**
+ * Sends the browser to Tempo Auth's pages to sign in, keeping the redirect's state in `storage`.
+ *
+ * @example
+ * ```ts
+ * await Actions.redirect(auth, { accessKey })
+ * ```
+ */
+export declare function redirect(auth: Auth, options: redirect.Options): Promise<void>;
+export declare namespace redirect {
+    type Options = {
+        /** What the app's key may do. Tempo Auth's pages show it, and the person approves it. */
+        accessKey: AccessKey;
+    };
+}
+/**
+ * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.
+ *
+ * @example
+ * ```ts
+ * const tokens = await Actions.refresh(auth, {
+ *   refreshToken: saved.tokens.refreshToken,
+ * })
+ * ```
+ */
+export declare function refresh(auth: Auth, options: refresh.Options): Promise<Tokens>;
+export declare namespace refresh {
+    type Options = {
+        /** The latest refresh token. Each refresh rotates it. */
+        refreshToken: string;
+    };
+}
+/**
+ * Emails the person a sign-in code. The response is the same for every address.
+ *
+ * @example
+ * ```ts
+ * await Actions.sendCode(auth, { email: 'person@example.com' })
+ * ```
+ */
+export declare function sendCode(auth: Auth, options: sendCode.Options): Promise<void>;
+export declare namespace sendCode {
+    type Options = {
+        /** The person's email address. */
+        email: string;
+    };
+}
+/**
+ * Sends the browser to an OAuth provider, or to the SSO connection a {@link Step} names, and back to
+ * `returnTo` signed in to Tempo Auth. The app then calls {@link authorize}.
+ *
+ * @example
+ * ```ts
+ * Actions.signIn(auth, { provider: 'google' })
+ * ```
+ */
+export declare function signIn(auth: Auth, options: signIn.Options): void;
+export declare namespace signIn {
+    type Options = ({
+        /** The OAuth provider to sign in with, from `getProviders`. */
+        provider: Provider;
+    } | {
+        /** The URL of a `Step`, such as the SSO connection an address requires. */
+        url: string;
+    }) & {
+        /** Where to return. Defaults to the current page. It must be on an internal origin. */
+        returnTo?: string | undefined;
+    };
+}
+/**
+ * Ends the person's Tempo Auth session, which signs them out of every app that relies on it.
+ *
+ * @example
+ * ```ts
+ * await Actions.signOut(auth)
+ * ```
+ */
+export declare function signOut(auth: Auth): Promise<void>;
+/**
+ * Signs the person in with the code they were emailed, and authorizes the app in the same call.
+ * Returns a {@link Step} when the address requires SSO, which {@link signIn} continues.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.verifyCode(auth, { accessKey, code, email })
+ * if ('step' in result) Actions.signIn(auth, { url: result.step.url })
+ * ```
+ */
+export declare function verifyCode(auth: Auth, options: verifyCode.Options): Promise<verifyCode.ReturnType>;
+export declare namespace verifyCode {
+    type Options = {
+        /** What the app's key may do. It must fit the headless ceiling. */
+        accessKey: AccessKey;
+        /** The 6-digit code the person was emailed. */
+        code: string;
+        /** The address the code was sent to. */
+        email: string;
+    };
+    /** The authorization, or the step the address requires first. */
+    type ReturnType = Authorization | {
+        step: Step;
+    };
+}

package/dist/Actions.js

@@ -0,0 +1,372 @@
+/**
+ * Tempo Auth's actions. Each takes an instance from `Auth.create`.
+ * @module
+ */
+import { Base64, Bytes, Hash, Hex } from 'ox';
+import { Secp256k1 } from 'viem/tempo';
+import { RequestError, } from './Auth.js';
+import * as Key from './Key.js';
+import { request } from './internal/request.js';
+/**
+ * Authorizes the app for a person already signed in to Tempo Auth, from any app. Returns
+ * `undefined` without a session, so the app shows sign-in. The key must fit Tempo Auth's headless
+ * ceiling.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.authorize(auth, { accessKey })
+ * if (!authorization) showSignIn()
+ * ```
+ */
+export async function authorize(auth, options) {
+    // Checking the session first answers a visitor without one with no failed request.
+    const session = await json(await (auth.fetch ?? fetch)(new URL('/api/auth/session', auth.url), {
+        credentials: 'include',
+    }));
+    if (!session.user)
+        return undefined;
+    const privateKey = Secp256k1.randomPrivateKey();
+    const response = await post(auth, '/api/authorize', {
+        json: request(auth, { ...options, privateKey }),
+    });
+    if (response.status === 401)
+        return undefined;
+    return authorization(await json(response), { privateKey });
+}
+/**
+ * Starts the device grant for a CLI: the person approves `userCode` at `verificationUri` from any
+ * browser, and `wait` resolves once they do.
+ *
+ * @example
+ * ```ts
+ * const device = await Actions.authorizeDevice(auth, { accessKey, device: Os.hostname() })
+ * console.log(`Open ${device.verificationUriComplete}`)
+ * const authorization = await device.wait()
+ * ```
+ */
+export async function authorizeDevice(auth, options) {
+    const privateKey = Secp256k1.randomPrivateKey();
+    const code = await json(await post(auth, '/api/device/authorize', {
+        json: {
+            device: options.device,
+            keyAuthorization: request(auth, { ...options, privateKey })
+                .keyAuthorization,
+        },
+    }));
+    /** Polls until the person approves or denies the code, or it expires. */
+    async function wait() {
+        let interval = code.interval;
+        const deadline = Date.now() + code.expires_in * 1000;
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, interval * 1000));
+            const response = await post(auth, '/api/device/token', {
+                json: { device_code: code.device_code },
+            });
+            const body = (await response.json());
+            if ('access_token' in body)
+                return authorization({
+                    account: body.account,
+                    keyAuthorization: body.key_authorization,
+                    tokens: tokens(body),
+                }, { privateKey });
+            // RFC 8628 asks a client told to slow down to add 5 seconds to its interval.
+            if (body.error === 'slow_down')
+                interval += 5;
+            else if (body.error !== 'authorization_pending')
+                throw new RequestError({
+                    message: `Sign-in failed: ${body.error}.`,
+                    status: response.status,
+                });
+        }
+        throw new RequestError({ message: 'The code expired.', status: 400 });
+    }
+    return {
+        expiresIn: code.expires_in,
+        userCode: code.user_code,
+        verificationUri: code.verification_uri,
+        verificationUriComplete: code.verification_uri_complete,
+        wait,
+    };
+}
+/**
+ * Returns the URL that signs the person in on Tempo Auth's pages and redirects back with a code
+ * and the key authorization, and the {@link Pending} state to keep until then, such as in a
+ * sealed cookie. {@link handleCallback} finishes it.
+ *
+ * @example
+ * ```ts
+ * const { pending, url } = await Actions.createAuthorizationUrl(auth, {
+ *   accessKey,
+ *   redirectUri: 'https://app.example/auth/callback',
+ * })
+ * await seal(c, 'oauth', pending)
+ * return c.redirect(url)
+ * ```
+ */
+export async function createAuthorizationUrl(auth, options) {
+    const redirectUri = options.redirectUri ?? auth.redirectUri ?? `${window.location.origin}/`;
+    const pending = {
+        privateKey: Secp256k1.randomPrivateKey(),
+        redirectUri,
+        state: crypto.randomUUID(),
+        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 };
+}
+/**
+ * Lists the OAuth providers Tempo Auth offers, for an app that shows its own sign-in buttons.
+ *
+ * @example
+ * ```ts
+ * const providers = await Actions.getProviders(auth)
+ * // [{ id: 'google', name: 'Google' }]
+ * ```
+ */
+export async function getProviders(auth) {
+    const { providers } = await json(await (auth.fetch ?? fetch)(new URL('/api/auth/providers', auth.url)));
+    return providers;
+}
+/**
+ * Finishes a sign-in redirect: checks its state, redeems the code with the PKCE verifier (and the
+ * client secret, for a backend), and reads the key authorization from the callback URL.
+ *
+ * @example
+ * ```ts
+ * const authorization = await Actions.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');
+    const account = params.get('account');
+    const keyAuthorization = params.get('key_authorization');
+    if (!code ||
+        !account ||
+        !keyAuthorization ||
+        params.get('state') !== pending.state)
+        throw new RequestError({
+            message: 'Sign-in failed. Start again.',
+            status: 400,
+        });
+    return authorization({
+        account: account,
+        keyAuthorization: JSON.parse(Base64.toString(keyAuthorization)),
+        tokens: await token(auth, {
+            code,
+            code_verifier: pending.verifier,
+            grant_type: 'authorization_code',
+            redirect_uri: pending.redirectUri,
+        }),
+    }, pending);
+}
+/**
+ * Finishes a {@link redirect} 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.handleRedirect(auth)) ??
+ *   (await Actions.authorize(auth, { accessKey }))
+ * ```
+ */
+export function handleRedirect(auth) {
+    redirected ??= (async () => {
+        const stored = storage(auth).getItem(storageKey);
+        storage(auth).removeItem(storageKey);
+        const url = new URL(window.location.href);
+        if (!stored || !url.searchParams.has('code'))
+            return undefined;
+        // The app keeps its own query and fragment, without the callback's parameters.
+        const clean = new URL(url);
+        for (const name of ['account', 'code', 'key_authorization', 'state'])
+            clean.searchParams.delete(name);
+        window.history.replaceState(null, '', clean.pathname + clean.search + clean.hash);
+        return handleCallback(auth, { pending: JSON.parse(stored), url });
+    })();
+    return redirected;
+}
+/**
+ * Sends the browser to Tempo Auth's pages to sign in, keeping the redirect's state in `storage`.
+ *
+ * @example
+ * ```ts
+ * await Actions.redirect(auth, { accessKey })
+ * ```
+ */
+export async function redirect(auth, options) {
+    const { pending, url } = await createAuthorizationUrl(auth, options);
+    storage(auth).setItem(storageKey, JSON.stringify(pending));
+    window.location.assign(url);
+}
+/**
+ * Exchanges a refresh token for new tokens. Refresh tokens rotate, so store the new one.
+ *
+ * @example
+ * ```ts
+ * const tokens = await Actions.refresh(auth, {
+ *   refreshToken: saved.tokens.refreshToken,
+ * })
+ * ```
+ */
+export function refresh(auth, options) {
+    return token(auth, {
+        grant_type: 'refresh_token',
+        refresh_token: options.refreshToken,
+    });
+}
+/**
+ * Emails the person a sign-in code. The response is the same for every address.
+ *
+ * @example
+ * ```ts
+ * await Actions.sendCode(auth, { email: 'person@example.com' })
+ * ```
+ */
+export async function sendCode(auth, options) {
+    await json(await post(auth, '/api/auth/code', { json: options }));
+}
+/**
+ * Sends the browser to an OAuth provider, or to the SSO connection a {@link Step} names, and back to
+ * `returnTo` signed in to Tempo Auth. The app then calls {@link authorize}.
+ *
+ * @example
+ * ```ts
+ * Actions.signIn(auth, { provider: 'google' })
+ * ```
+ */
+export function signIn(auth, options) {
+    const url = 'url' in options
+        ? new URL(options.url)
+        : new URL(`/api/auth/oauth/${options.provider}`, auth.url);
+    url.searchParams.set('return_to', options.returnTo ?? window.location.href);
+    window.location.assign(url);
+}
+/**
+ * Ends the person's Tempo Auth session, which signs them out of every app that relies on it.
+ *
+ * @example
+ * ```ts
+ * await Actions.signOut(auth)
+ * ```
+ */
+export async function signOut(auth) {
+    // A JSON body keeps the request out of Tempo Auth's CSRF check for cross-site form posts.
+    await json(await post(auth, '/api/auth/logout', { json: {} }));
+}
+/**
+ * Signs the person in with the code they were emailed, and authorizes the app in the same call.
+ * Returns a {@link Step} when the address requires SSO, which {@link signIn} continues.
+ *
+ * @example
+ * ```ts
+ * const result = await Actions.verifyCode(auth, { accessKey, code, email })
+ * if ('step' in result) Actions.signIn(auth, { url: result.step.url })
+ * ```
+ */
+export async function verifyCode(auth, options) {
+    const { accessKey, code, email } = options;
+    const privateKey = Secp256k1.randomPrivateKey();
+    const body = await json(await post(auth, '/api/auth/code/verify', {
+        json: {
+            authorize: request(auth, { accessKey, privateKey }),
+            code,
+            email,
+        },
+    }));
+    if ('step' in body)
+        return {
+            step: { ...body.step, url: new URL(body.step.url, auth.url).href },
+        };
+    return authorization(body.authorization, { privateKey });
+}
+/** 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 redirected;
+/** Where a redirect keeps its state in `storage`. */
+const storageKey = 'tempo-auth:redirect';
+/** Builds an authorization from what Tempo Auth returned and the key the app generated. */
+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 {
+        account: Key.toAccount(key),
+        key,
+        tokens: tokens_,
+        user: { email: claims.email, id: claims.sub },
+    };
+}
+/** Reads a JSON response, and throws a {@link RequestError} for a refused request. */
+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. */
+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',
+    });
+}
+/** Where a redirect keeps its state: the instance's `storage`, or the page's session storage. */
+function storage(auth) {
+    return auth.storage ?? sessionStorage;
+}
+/**
+ * Calls Tempo Auth's OAuth token endpoint, adding the client and any secret. It forwards standard
+ * OAuth form posts to WorkOS.
+ */
+async function token(auth, body) {
+    return tokens(await 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`. */
+function tokens(response) {
+    return {
+        accessToken: response.access_token,
+        expiresAt: Date.now() + response.expires_in * 1000,
+        idToken: response.id_token,
+        refreshToken: response.refresh_token,
+    };
+}

package/dist/Auth.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A Tempo Auth instance, and the types its actions take and return. Create one with
+ * {@link create}, then pass it to each action in `Actions`. Every sign-in returns an
+ * {@link Authorization}: the person's tokens, and a viem access key account.
+ *
+ * @example
+ * ```ts
+ * import { Actions, Auth } from '@tempoxyz/auth'
+ * import { Addresses, Expiry, Scopes } from 'viem/tempo'
+ * import { tempoTestnet } from 'viem/tempo/chains'
+ *
+ * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
+ *
+ * const authorization = await Actions.authorize(auth, {
+ *   accessKey: {
+ *     chainId: tempoTestnet.id,
+ *     expiry: Expiry.days(1),
+ *     limits: [{ limit: 10_000_000n, token: Addresses.pathUsd }],
+ *     scopes: [Scopes.tip20(Addresses.pathUsd).transfer()],
+ *   },
+ * })
+ * ```
+ * @module
+ */
+import type { Hex } from 'ox';
+import type { KeyAuthorization } from 'ox/tempo';
+import type * as Key from './Key.ts';
+/** A Tempo Auth instance, which every action takes. */
+export type Auth = {
+    /** The app's Connect client ID. */
+    clientId: string;
+    /** The app's client secret. Only a backend holds one. */
+    clientSecret?: string | undefined;
+    /** Calls Tempo Auth. Defaults to the global `fetch`. */
+    fetch?: typeof globalThis.fetch | undefined;
+    /** Where Tempo Auth redirects back to. Defaults to the page's origin in a browser. */
+    redirectUri?: string | undefined;
+    /** The scopes the app's tokens carry. */
+    scope: string;
+    /** Where a redirect sign-in keeps its state until Tempo Auth redirects back. */
+    storage?: Pick<Storage, 'getItem' | 'removeItem' | 'setItem'> | undefined;
+    /** Where Tempo Auth runs, such as `https://auth.tempo.xyz`. */
+    url: string;
+};
+/** What an app's access key may do, as viem's `accessKey.signAuthorization` takes it. */
+export type AccessKey = Pick<KeyAuthorization.KeyAuthorization, 'limits' | 'scopes'> & {
+    /** The chain the key acts on, such as `tempoTestnet.id`. */
+    chainId: number;
+    /** Unix seconds. viem's `Expiry` builds one, such as `Expiry.days(1)`. */
+    expiry: number;
+};
+/** What every sign-in returns. */
+export type Authorization = {
+    /** The app's access key, as a viem account acting for the person's Tempo Account. */
+    account: ReturnType<typeof Key.toAccount>;
+    /** The same key as JSON, for apps that store it and rebuild it with `Key.toAccount`. */
+    key: Key.Key;
+    /** The app's tokens for Tempo APIs. */
+    tokens: Tokens;
+    /** The signed-in person, from the ID token. */
+    user: User;
+};
+/** The app's tokens for Tempo APIs. */
+export type Tokens = {
+    /** The Bearer token Tempo APIs accept. */
+    accessToken: string;
+    /** When the access token expires, in milliseconds. */
+    expiresAt: number;
+    /** The OIDC ID token, which names the person. A refresh may omit it. */
+    idToken?: string | undefined;
+    /** Exchanges for new tokens through `Actions.refresh`. It rotates on every refresh. */
+    refreshToken?: string | undefined;
+};
+/** The signed-in person. */
+export type User = {
+    /** The person's verified email address. */
+    email: string;
+    /** The person's ID, the `sub` of every token. */
+    id: string;
+};
+/** An OAuth provider's short name, as `Actions.getProviders` lists them. */
+export type Provider = 'apple' | 'bitbucket' | 'github' | 'gitlab' | 'google' | 'intuit' | 'linkedin' | 'microsoft' | 'salesforce' | 'slack' | 'xero';
+/** A step a sign-in needs before it finishes, such as the SSO connection an address requires. */
+export type Step = {
+    /** The kind of step. */
+    type: 'sso';
+    /** Where `Actions.signIn` sends the browser to take the step. */
+    url: string;
+};
+/** A sign-in redirect in progress: what the app keeps until Tempo Auth redirects back. */
+export type Pending = {
+    /** The app's new access key, which the callback authorizes. */
+    privateKey: Hex.Hex;
+    /** Where Tempo Auth redirects back to, which the code exchange repeats. */
+    redirectUri: string;
+    /** The value the callback must echo, so a forged callback is refused. */
+    state: string;
+    /** The PKCE verifier that redeems the code. */
+    verifier: string;
+};
+/** A request Tempo Auth refused, with its status and message. */
+export declare class RequestError extends Error {
+    readonly name = "Auth.RequestError";
+    /** The HTTP status Tempo Auth answered. */
+    readonly status: number;
+    constructor(options: {
+        message: string;
+        status: number;
+    });
+}
+/**
+ * Creates a Tempo Auth instance.
+ *
+ * @example
+ * ```ts
+ * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
+ * ```
+ */
+export declare function create(options: create.Options): Auth;
+export declare namespace create {
+    type Options = Omit<Auth, 'scope'> & {
+        /**
+         * Scopes the app's tokens carry beyond `openid` and `email`, which every instance includes.
+         * Defaults to `offline_access`, for a refresh token.
+         */
+        scope?: string | undefined;
+    };
+}

package/dist/Auth.js

@@ -0,0 +1,26 @@
+/** A request Tempo Auth refused, with its status and message. */
+export class RequestError extends Error {
+    name = 'Auth.RequestError';
+    /** The HTTP status Tempo Auth answered. */
+    status;
+    constructor(options) {
+        super(options.message);
+        this.status = options.status;
+    }
+}
+/**
+ * Creates a Tempo Auth instance.
+ *
+ * @example
+ * ```ts
+ * const auth = Auth.create({ clientId: 'client_…', url: 'https://auth.tempo.xyz' })
+ * ```
+ */
+export function create(options) {
+    // Every authorization reads the person from the ID token, which needs `openid` and `email`.
+    const scopes = (options.scope ?? 'offline_access').split(' ').filter(Boolean);
+    return {
+        ...options,
+        scope: [...new Set(['openid', 'email', ...scopes])].join(' '),
+    };
+}

package/dist/Key.d.ts

@@ -0,0 +1,39 @@
+/**
+ * An app's access key on a person's Tempo Account, as the app stores it: the key, the account it
+ * acts for, and the authorization Tempo Auth signed for it.
+ * @module
+ */
+import type { Address, Hex } from 'ox';
+import { KeyAuthorization } from 'ox/tempo';
+import { Account } from 'viem/tempo';
+/** A stored access key. It is JSON, so servers and CLIs can keep it in a cookie or a file. */
+export type Key = {
+    /** The Tempo Account the key acts for. */
+    account: Address.Address;
+    /** The signed authorization, in the node's RPC format. */
+    keyAuthorization: KeyAuthorization.Rpc;
+    /** The access key's private key. Keep it as secret as a session. */
+    privateKey: Hex.Hex;
+};
+/**
+ * Whether the key's authorization has expired, so a new sign-in must authorize a new key.
+ *
+ * @example
+ * ```ts
+ * if (Key.expired(saved.key)) await signInAgain()
+ * ```
+ */
+export declare function expired(key: Key): boolean;
+/**
+ * Returns the key as a viem access key account acting for its Tempo Account. viem attaches the
+ * authorization to transactions until the chain registers the key.
+ *
+ * @example
+ * ```ts
+ * import { Key } from '@tempoxyz/auth'
+ *
+ * const account = Key.toAccount(key)
+ * await client.token.transferSync({ account, amount, to, token })
+ * ```
+ */
+export declare function toAccount(key: Key): Account.AccessKeyAccount;

package/dist/Key.js

@@ -0,0 +1,39 @@
+import { KeyAuthorization } from 'ox/tempo';
+import { Account, KeyAuthorizationManager } from 'viem/tempo';
+/**
+ * Whether the key's authorization has expired, so a new sign-in must authorize a new key.
+ *
+ * @example
+ * ```ts
+ * if (Key.expired(saved.key)) await signInAgain()
+ * ```
+ */
+export function expired(key) {
+    const { expiry } = KeyAuthorization.fromRpc(key.keyAuthorization);
+    return Boolean(expiry) && expiry * 1000 <= Date.now();
+}
+/**
+ * Returns the key as a viem access key account acting for its Tempo Account. viem attaches the
+ * authorization to transactions until the chain registers the key.
+ *
+ * @example
+ * ```ts
+ * import { Key } from '@tempoxyz/auth'
+ *
+ * const account = Key.toAccount(key)
+ * await client.token.transferSync({ account, amount, to, token })
+ * ```
+ */
+export function toAccount(key) {
+    const keyAuthorization = KeyAuthorization.fromRpc(key.keyAuthorization);
+    const keyAuthorizationManager = KeyAuthorizationManager.memory();
+    keyAuthorizationManager.set({
+        accessKey: keyAuthorization.address,
+        address: key.account,
+        chainId: Number(keyAuthorization.chainId),
+    }, keyAuthorization);
+    return Account.fromSecp256k1(key.privateKey, {
+        access: key.account,
+        keyAuthorizationManager,
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * as Actions from './Actions.ts';
+export * as Auth from './Auth.ts';
+export * as Key from './Key.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+// biome-ignore lint/performance/noBarrelFile: entrypoint module
+export * as Actions from './Actions.js';
+export * as Auth from './Auth.js';
+export * as Key from './Key.js';

package/dist/internal/request.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Builds the authorization and key authorization requests the actions send, in Tempo Auth's wire
+ * format. The root type check holds them to Tempo Auth's routes.
+ * @module
+ */
+import { Hex } from 'ox';
+import { Account } from 'viem/tempo';
+import type { AccessKey, Auth } from '../Auth.ts';
+/** The authorization request and key authorization request, in Tempo Auth's wire format. */
+export declare function request(auth: Auth, options: {
+    accessKey: AccessKey;
+    privateKey: Hex.Hex;
+}): {
+    client_id: string;
+    keyAuthorization: {
+        address: `0x${string}`;
+        chainId: `0x${string}`;
+        expiry: number;
+        keyType: 'secp256k1';
+        limits: {
+            limit: `0x${string}`;
+            period?: number;
+            token: `0x${string}`;
+        }[] | undefined;
+        scopes: readonly Account.z_KeyAuthorization.Scope<`0x${string}`>[] | undefined;
+    };
+    redirect_uri: string;
+    scope: string;
+};

package/dist/internal/request.js

@@ -0,0 +1,28 @@
+/**
+ * Builds the authorization and key authorization requests the actions send, in Tempo Auth's wire
+ * format. The root type check holds them to Tempo Auth's routes.
+ * @module
+ */
+import { Hex } from 'ox';
+import { Account } from 'viem/tempo';
+/** The authorization request and key authorization request, in Tempo Auth's wire format. */
+export function request(auth, options) {
+    const { accessKey, privateKey } = options;
+    return {
+        client_id: auth.clientId,
+        keyAuthorization: {
+            address: Account.fromSecp256k1(privateKey).address,
+            chainId: Hex.fromNumber(accessKey.chainId),
+            expiry: accessKey.expiry,
+            keyType: 'secp256k1',
+            limits: accessKey.limits?.map(({ limit, period, token }) => ({
+                limit: Hex.fromNumber(limit),
+                ...(period ? { period } : {}),
+                token,
+            })),
+            scopes: accessKey.scopes,
+        },
+        redirect_uri: auth.redirectUri ?? `${globalThis.location?.origin ?? auth.url}/`,
+        scope: auth.scope,
+    };
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@tempoxyz/auth",
+  "version": "0.0.0-pr-6.sha-17bb901",
+  "description": "Signs people in to Tempo through Tempo Auth, and returns viem access key accounts on their Tempo Accounts.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ox": "0.14.56"
+  },
+  "peerDependencies": {
+    "viem": ">=2.57.5-0"
+  },
+  "devDependencies": {
+    "typescript": "7.0.2",
+    "viem": "https://pkg.pr.new/viem@0872b53"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check:types": "tsc"
+  }
+}