@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/client/Decorator.ts

@@ -0,0 +1,410 @@
+/**
+ * `tempoId`, a Viem client extension that adds Tempo ID's actions as `client.auth`. It reads the
+ * chain from the client, and sets the client's {@link Auth.Account} at each sign-in, so the client
+ * sends with the signed-in user's access key.
+ *
+ * @example
+ * ```ts
+ * import { Auth, tempoId } from '@tempoxyz/id/client'
+ * import { createClient } from 'viem/tempo'
+ * import { tempoTestnet } from 'viem/tempo/chains'
+ *
+ * const client = createClient({
+ *   account: Auth.account(),
+ *   chain: tempoTestnet,
+ * }).extend(tempoId({ clientId: 'client_…' }))
+ *
+ * await client.auth.email.signIn({ code, email })
+ * await client.token.transferSync({ amount, to, token })
+ * ```
+ * @module
+ */
+import type { Chain, Client, Transport } from 'viem'
+import type { Account as ViemAccount } from 'viem/tempo'
+import * as Actions from './Actions.js'
+import * as Auth from './Auth.js'
+import type { Authorization } from './Authorization.js'
+import * as AccountState from './internal/account.js'
+import * as Key from './Key.js'
+import type * as Pending from './Pending.js'
+import type { User } from './User.js'
+
+/** A client created without `account: Auth.account()`, which the extension sets at sign-in. */
+export class AccountRequiredError extends Error {
+  override readonly name = 'Decorator.AccountRequiredError'
+
+  constructor() {
+    super(
+      'The client has no Tempo ID account. Create the client with `account: Auth.account()`.',
+    )
+  }
+}
+
+/** A client created without a chain, which the extension reads the instance's `chainId` from. */
+export class ChainRequiredError extends Error {
+  override readonly name = 'Decorator.ChainRequiredError'
+
+  constructor() {
+    super('The client has no chain. Create the client with a Tempo `chain`.')
+  }
+}
+
+/**
+ * A sign-in that another sign-in or a sign-out overtook. The client keeps the newer state, so the
+ * overtaken authorization is never returned to sign with.
+ */
+export class SupersededError extends Error {
+  override readonly name = 'Decorator.SupersededError'
+
+  constructor() {
+    super(
+      'Another sign-in or a sign-out completed while this sign-in was pending. Sign in again.',
+    )
+  }
+}
+
+/**
+ * Returns a Viem client extension that adds Tempo ID's actions as `client.auth`. Each member calls
+ * the action of the same name in `Actions` with one instance, whose `chainId` is the client's chain.
+ * Each sign-in sets the client's account to the authorization's, and `signOut` empties it at once.
+ * A sign-in that another sign-in or a sign-out overtook throws {@link SupersededError}. Throws
+ * {@link ChainRequiredError} for a client without a chain, and {@link AccountRequiredError} for one
+ * whose account is not an `Auth.account()`.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({
+ *   account: Auth.account(),
+ *   chain: tempoTestnet,
+ * }).extend(tempoId({ clientId: 'client_…' }))
+ * ```
+ */
+export function tempoId(options: tempoId.Options) {
+  return <transport extends Transport, chain extends Chain>(
+    client: Client<transport, chain, Auth.Account>,
+  ): tempoId.Decorator<chain['id']> => {
+    if (!client.chain) throw new ChainRequiredError()
+    const state = (client.account as Partial<Auth.Account> | undefined)?.[
+      AccountState.key
+    ]
+    if (!state) throw new AccountRequiredError()
+
+    const auth = Auth.create({ ...options, chainId: client.chain.id })
+
+    // Counts changes to the client's account. Each sign-in applies its result only when no other
+    // sign-in or sign-out completed after it began. A stale result never replaces a newer one,
+    // and a sign-in still pending at sign-out never signs the client back in.
+    let version = 0
+    // The version that the latest sign-out produced, until another change follows it.
+    let signedOut: number | undefined
+    // The redirect result that `complete` settled on this page load.
+    let completing:
+      | Promise<Actions.redirect.complete.ReturnType<boolean>>
+      | undefined
+
+    /**
+     * Begins an operation that changes the client's account. `apply` applies its result: the
+     * account to sign with, or `undefined` to stop signing. `check` accepts a result that changes
+     * no account, such as a step. Applying an account, or checking a step, that a newer change
+     * overtook throws {@link SupersededError}. The caller never holds a result that the
+     * client's newer state contradicts. `settle` applies a result's account, or empties the account
+     * for a result without a key. `fail` rethrows the operation's error, or throws `SupersededError`
+     * when a newer change overtook it, so the caller never acts on a stale refusal. A refusal marked
+     * `signedIn` also empties the account, since the user whom the sign-in signed in does not hold it.
+     */
+    const begin = () => {
+      const started = version
+      // A sign-in that finishes after sign-out can set a new server session, so it ends that
+      // session again, unless a newer change already followed the sign-out.
+      const superseded = async () => {
+        if (signedOut === version) await Actions.signOut(auth)
+        return new SupersededError()
+      }
+      return {
+        async apply(account: ViemAccount.AccessKeyAccount | undefined) {
+          if (version !== started) {
+            if (account) throw await superseded()
+            return
+          }
+          state.account = account
+          version++
+        },
+        async check() {
+          if (version !== started) throw await superseded()
+        },
+        // An arrow function, which `catch` takes unbound.
+        fail: async (error: unknown): Promise<never> => {
+          if (version !== started) throw await superseded()
+          if (error instanceof Auth.RequestError && error.signedIn) {
+            state.account = undefined
+            version++
+          }
+          throw error
+        },
+        async settle(
+          result: Authorization | Actions.redirect.handleCallback.WithoutKey,
+        ) {
+          if ('account' in result) return this.apply(result.account)
+          // The check and the change run with no `await` between them, so no other change lands
+          // after the check, and an overtaken result throws even without an account.
+          if (version !== started) throw await superseded()
+          state.account = undefined
+          version++
+        },
+      }
+    }
+
+    return {
+      auth: {
+        account: {
+          get: () => Actions.account.get(auth),
+        },
+        async authorize(options = {}) {
+          const change = begin()
+          const authorization = await Actions.authorize(auth, options)
+          // Without a session, the client stops signing as the user it last authorized.
+          if (authorization) await change.settle(authorization)
+          else await change.apply(undefined)
+          return authorization
+        },
+        device: {
+          async authorize(options = {}) {
+            const change = begin()
+            const device = await Actions.device.authorize(auth, options)
+            return {
+              ...device,
+              async wait() {
+                const authorization = await device.wait()
+                await change.apply(authorization.account)
+                return authorization
+              },
+            }
+          },
+        },
+        email: {
+          sendCode: (options) => Actions.email.sendCode(auth, options),
+          async signIn(options) {
+            const change = begin()
+            const authorization = await Actions.email
+              .signIn(auth, options)
+              .catch(change.fail)
+            await change.settle(authorization)
+            return authorization
+          },
+        },
+        instance: auth,
+        oauth: {
+          introspect: (options) => Actions.oauth.introspect(auth, options),
+          jwks: () => Actions.oauth.jwks(auth),
+          userInfo: (options) => Actions.oauth.userInfo(auth, options),
+        },
+        passkey: {
+          async signIn(options = {}) {
+            const change = begin()
+            const result = await Actions.passkey
+              .signIn(auth, options)
+              .catch(change.fail)
+            if ('step' in result) await change.check()
+            else await change.settle(result)
+            return result
+          },
+        },
+        provider: {
+          list: () => Actions.provider.list(auth),
+          signIn: (options) => Actions.provider.signIn(auth, options),
+        },
+        realm: {
+          list: () => Actions.realm.list(auth),
+        },
+        redirect: {
+          complete(options = {}) {
+            // A page load settles its redirect once, so a later call never applies a result that a
+            // newer sign-in replaced.
+            completing ??= (async () => {
+              const change = begin()
+              const authorization = await Actions.redirect.complete(
+                auth,
+                options,
+              )
+              // `undefined` means the page is not a callback, which shows nothing about the session.
+              if (authorization) await change.settle(authorization)
+              return authorization
+            })()
+            // The first call's `key` typed the settled result, which later calls share.
+            return completing as never
+          },
+          createUrl: (options = {}) =>
+            Actions.redirect.createUrl(auth, options),
+          async handleCallback(options) {
+            const change = begin()
+            const authorization = await Actions.redirect.handleCallback(
+              auth,
+              options,
+            )
+            await change.settle(authorization)
+            return authorization
+          },
+          start: (options = {}) => Actions.redirect.start(auth, options),
+        },
+        refresh: (options) => Actions.refresh(auth, options),
+        restore: (authorization, options = {}) => {
+          // A sign-in stored before `Key.chainId` existed gains it here.
+          const key = Key.from(authorization.key)
+          const account = Key.toAccount(key, options)
+          state.account = account
+          version++
+          return { ...authorization, account, key }
+        },
+        async signOut() {
+          // The client stops signing at once, even when the request fails, and any sign-in still
+          // pending is discarded, since the user asked to leave.
+          state.account = undefined
+          version++
+          signedOut = version
+          await Actions.signOut(auth)
+        },
+      },
+    }
+  }
+}
+
+export declare namespace tempoId {
+  /** `Auth.create`'s options, without `chainId`, which the extension reads from the client. */
+  type Options = Omit<Auth.create.Options, 'chainId'>
+
+  /**
+   * What the extension adds to a client on the chain `chainId`. Each member's `permissions.chainId`
+   * defaults to `chainId`, and an override names another chain.
+   */
+  type Decorator<chainId extends number> = {
+    /** Tempo ID's actions, with the extension's instance. */
+    auth: {
+      /** Actions for the user's Tempo Account. */
+      account: {
+        /** `Actions.account.get`. */
+        get: () => Promise<Actions.account.get.ReturnType>
+      }
+      /**
+       * `Actions.authorize`, which sets the client's account, or empties it for an authorization
+       * without a key or a user without a session.
+       */
+      authorize: <
+        const id extends number = chainId,
+        const key extends boolean = true,
+      >(
+        options?: Actions.authorize.Options<id, key>,
+      ) => Promise<Actions.authorize.ReturnType<id, key>>
+      /** Actions for device authorization grants. */
+      device: {
+        /** `Actions.device.authorize`, whose `wait` sets the client's account. */
+        authorize: <const id extends number = chainId>(
+          options?: Actions.device.authorize.Options<id>,
+        ) => Promise<Actions.device.authorize.ReturnType<id>>
+      }
+      /** Actions for sign-in with an emailed code. */
+      email: {
+        /** `Actions.email.sendCode`. */
+        sendCode: (options: Actions.email.sendCode.Options) => Promise<void>
+        /**
+         * `Actions.email.signIn`, which sets the client's account, or empties it for a sign-in without
+         * a key, or for a refusal whose `signedIn` is `true`. A sign-in that another sign-in or a
+         * sign-out overtook throws {@link SupersededError}.
+         */
+        signIn: <
+          const id extends number = chainId,
+          const key extends boolean = true,
+        >(
+          options: Actions.email.signIn.Options<id, key>,
+        ) => Promise<Actions.email.signIn.ReturnType<id, key>>
+      }
+      /** The instance the members call `Actions` with. */
+      instance: Auth.Auth
+      /** Actions for the issuer's OAuth endpoints. */
+      oauth: {
+        /** `Actions.oauth.introspect`. */
+        introspect: (
+          options: Actions.oauth.introspect.Options,
+        ) => Promise<Actions.oauth.introspect.ReturnType>
+        /** `Actions.oauth.jwks`. */
+        jwks: () => Promise<Actions.oauth.jwks.ReturnType>
+        /** `Actions.oauth.userInfo`. */
+        userInfo: (options: Actions.oauth.userInfo.Options) => Promise<User>
+      }
+      /** Actions for sign-in with a passkey. */
+      passkey: {
+        /**
+         * `Actions.passkey.signIn`, which sets the client's account unless it returns a step, as
+         * `auth.email.signIn` does. A step or sign-in that another sign-in or a sign-out overtook
+         * throws {@link SupersededError}.
+         */
+        signIn: <
+          const id extends number = chainId,
+          const key extends boolean = true,
+        >(
+          options?: Actions.passkey.signIn.Options<id, key>,
+        ) => Promise<Actions.passkey.signIn.ReturnType<id, key>>
+      }
+      /** Actions for sign-in with an identity provider, such as Google or SSO. */
+      provider: {
+        /** `Actions.provider.list`. */
+        list: () => Promise<Actions.provider.list.ReturnType>
+        /** `Actions.provider.signIn`. */
+        signIn: (options: Actions.provider.signIn.Options) => void
+      }
+      /** Actions for the realms the app reaches. */
+      realm: {
+        /** `Actions.realm.list`. */
+        list: () => Promise<Actions.realm.list.ReturnType>
+      }
+      /** Actions for sign-in through a redirect to Tempo ID's pages. */
+      redirect: {
+        /**
+         * `Actions.redirect.complete`, which sets the client's account, or empties it for a sign-in
+         * without a key. The first call settles the page load's redirect, and later calls return
+         * the same result.
+         */
+        complete: <const key extends boolean = true>(
+          options?: Actions.redirect.complete.Options<key>,
+        ) => Promise<Actions.redirect.complete.ReturnType<key>>
+        /** `Actions.redirect.createUrl`. */
+        createUrl: <const key extends boolean = true>(
+          options?: Actions.redirect.createUrl.Options<key>,
+        ) => Promise<Actions.redirect.createUrl.ReturnType<key>>
+        /**
+         * `Actions.redirect.handleCallback`, which sets the client's account, or empties it for a
+         * sign-in without a key.
+         */
+        handleCallback: <
+          const pending extends Pending.Pending | Pending.WithoutKey =
+            Pending.Pending,
+        >(
+          options: Actions.redirect.handleCallback.Options<pending>,
+        ) => Promise<Actions.redirect.handleCallback.ReturnType<pending>>
+        /** `Actions.redirect.start`. */
+        start: (options?: Actions.redirect.start.Options) => Promise<void>
+      }
+      /** `Actions.refresh`. */
+      refresh: (
+        options: Actions.refresh.Options,
+      ) => ReturnType<typeof Actions.refresh>
+      /**
+       * Rebuilds a stored authorization's account with `Key.toAccount`, sets the client's account to
+       * it, and returns the authorization. `Key.from` fills the key's `chainId` when a sign-in stored
+       * before it existed leaves it out. Throws `Key.AccessKeyRequiredError` for a key that carries
+       * no material without the `accessKey` the app supplied.
+       */
+      restore: <id extends number = chainId>(
+        authorization: Omit<Authorization<id>, 'account' | 'key'> & {
+          /** The stored key, with or without its `chainId`. */
+          key: Key.from.Value<id>
+        },
+        options?: Key.toAccount.Options,
+      ) => Authorization<id>
+      /**
+       * `Actions.signOut`, which empties the client's account before the request, even when it
+       * fails, and discards any sign-in still pending.
+       */
+      signOut: () => Promise<void>
+    }
+  }
+}

package/src/client/Key.ts

@@ -0,0 +1,140 @@
+/**
+ * An app's access key on a user's Tempo Account, as the app stores it: the account it acts for,
+ * the authorization Tempo ID signed for it, and the key material the library generated.
+ * @module
+ */
+import { type Address, type Hex, PublicKey, type WebCryptoP256 } from 'ox'
+import { KeyAuthorization } from 'ox/tempo'
+import type { OneOf } from 'viem'
+import { Account, KeyAuthorizationManager } from 'viem/tempo'
+
+/**
+ * A stored access key. A browser key is a non-extractable WebCrypto key pair, which IndexedDB
+ * keeps without exporting. Elsewhere it is a secp256k1 private key, as JSON for a cookie or a file.
+ * A key the app supplied as `accessKey` carries no material.
+ */
+export type Key<chainId extends number = number> = {
+  /** The Tempo Account the key acts for. */
+  account: Address.Address
+  /** The chain the key acts on, from its authorization. */
+  chainId: chainId
+  /** The signed authorization, in the node's RPC format. */
+  keyAuthorization: KeyAuthorization.Rpc
+} & Material
+
+/** The key material the library generated for a sign-in. */
+export type Material = OneOf<
+  | {
+      /** A non-extractable WebCrypto P256 key pair, in a browser. */
+      keyPair: WebCryptoP256.createKeyPair.ReturnType
+    }
+  | {
+      /** A secp256k1 private key, outside a browser. Keep it as secret as a session. */
+      privateKey: Hex.Hex
+    }
+  | {}
+>
+
+/** A key the app supplied as `accessKey`, which `toAccount` needs to rebuild its account. */
+export class AccessKeyRequiredError extends Error {
+  override readonly name = 'Key.AccessKeyRequiredError'
+
+  constructor() {
+    super('The key carries no material. Pass the `accessKey` the app supplied.')
+  }
+}
+
+/**
+ * Whether the key's authorization is expired, so a new sign-in must authorize a new key.
+ *
+ * @example
+ * ```ts
+ * if (Key.expired(saved.key)) await signInAgain()
+ * ```
+ */
+export function expired(key: Key) {
+  const { expiry } = KeyAuthorization.fromRpc(key.keyAuthorization)
+  return Boolean(expiry) && expiry! * 1000 <= Date.now()
+}
+
+/**
+ * Instantiates a {@link Key}. Fills `chainId` from the key authorization when the value leaves it
+ * out, as a key stored before `chainId` existed does.
+ *
+ * @example
+ * ```ts
+ * const key = Key.from(JSON.parse(saved).key)
+ * ```
+ */
+export function from<chainId extends number = number>(
+  value: from.Value<chainId>,
+): Key<chainId> {
+  if (value.chainId !== undefined) return { ...value, chainId: value.chainId }
+  // The node signs the chain ID the request named, so it is the request's literal.
+  const chainId = Number(
+    KeyAuthorization.fromRpc(value.keyAuthorization).chainId,
+  ) as chainId
+  return { ...value, chainId }
+}
+
+export declare namespace from {
+  type Value<chainId extends number = number> = {
+    /** The Tempo Account the key acts for. */
+    account: Address.Address
+    /** The chain the key acts on. Defaults to the key authorization's. */
+    chainId?: chainId | undefined
+    /** The signed authorization, in the node's RPC format. */
+    keyAuthorization: KeyAuthorization.Rpc
+  } & Material
+}
+
+/**
+ * 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. A key the app supplied signs
+ * with that `accessKey`. Throws {@link AccessKeyRequiredError} when neither holds key material.
+ *
+ * @example
+ * ```ts
+ * import { Key } from '@tempoxyz/id/client'
+ *
+ * const account = Key.toAccount(key)
+ * await client.token.transferSync({ account, amount, to, token })
+ * ```
+ */
+export function toAccount(
+  key: Key,
+  options: toAccount.Options = {},
+): Account.AccessKeyAccount {
+  const { accessKey } = options
+  const keyAuthorization = KeyAuthorization.fromRpc(key.keyAuthorization)
+  const keyAuthorizationManager = KeyAuthorizationManager.memory()
+  // The memory manager stores synchronously, so the authorization is in place before the account
+  // is returned.
+  void keyAuthorizationManager.set(
+    {
+      accessKey: keyAuthorization.address,
+      address: key.account,
+      chainId: Number(keyAuthorization.chainId),
+    },
+    keyAuthorization,
+  )
+  const access = { access: key.account, keyAuthorizationManager }
+
+  if (key.keyPair) return Account.fromWebCryptoP256(key.keyPair, access)
+  if (key.privateKey) return Account.fromSecp256k1(key.privateKey, access)
+  if (!accessKey) throw new AccessKeyRequiredError()
+  // A raw signature is the key's own, which the bound account wraps for the Tempo Account.
+  return Account.from({
+    ...access,
+    keyType: accessKey.keyType,
+    publicKey: PublicKey.fromHex(accessKey.publicKey),
+    sign: (parameters) => accessKey.sign({ ...parameters, raw: true }),
+  })
+}
+
+export declare namespace toAccount {
+  type Options = {
+    /** The key the app supplied to the sign-in, for a key that carries no material. */
+    accessKey?: Account.Account | undefined
+  }
+}

package/src/client/Pending.ts

@@ -0,0 +1,46 @@
+/**
+ * A sign-in redirect in progress, which an app keeps until Tempo ID redirects back.
+ * @module
+ */
+import type * as Key from './Key.js'
+
+/**
+ * A sign-in redirect in progress: what the app keeps until Tempo ID redirects back, with the
+ * material of the new access key the callback authorizes. {@link WithoutKey} is a redirect that
+ * authorizes no key.
+ */
+export type Pending = Key.Material &
+  Base & {
+    /** Absent, since the redirect authorizes a key. */
+    key?: undefined
+  }
+
+/** What every sign-in redirect keeps. */
+type Base = {
+  /** Where Tempo ID 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 redirect that authorizes no access key. */
+export type WithoutKey = Base & {
+  /** `false`, since the redirect authorizes no key. */
+  key: false
+}
+
+/**
+ * Instantiates a {@link Pending}, or a {@link WithoutKey}.
+ *
+ * @example
+ * ```ts
+ * const pending = Pending.from(await unseal(c, 'oauth'))
+ * ```
+ */
+export function from<const value extends Pending | WithoutKey>(
+  value: value,
+): value {
+  return value
+}

package/src/client/Permissions.ts

@@ -0,0 +1,39 @@
+/**
+ * What an app's access key may do: its chain, expiry, spending limits, and call scopes.
+ * @module
+ */
+import type { KeyAuthorization } from 'ox/tempo'
+
+/**
+ * What an app's access key may do, as Viem's `accessKey.authorize` takes it. Tempo ID fills what
+ * it leaves out with the headless ceiling. `chainId` carries the chain's ID as a literal type, which
+ * the authorization's `key.chainId` keeps.
+ */
+export type Permissions<chainId extends number = number> = {
+  /** The chain the key acts on, such as `tempoTestnet.id`. Defaults to the instance's `chainId`. */
+  chainId?: chainId | undefined
+  /** Unix seconds. Viem's `Expiry` builds one, such as `Expiry.days(1)`. Defaults to a year from now. */
+  expiry?: number | undefined
+  /** How much of each token the key may spend, in total or, with a `period` in seconds, per period. Defaults to about $1,000 of each token it calls, or of OUSD. */
+  limits?: KeyAuthorization.KeyAuthorization['limits']
+  /** The calls the key may make. Defaults to transfers of each token it limits. */
+  scopes?: KeyAuthorization.KeyAuthorization['scopes']
+}
+
+/**
+ * Instantiates a {@link Permissions}, keeping `chainId` as a literal type.
+ *
+ * @example
+ * ```ts
+ * const permissions = Permissions.from({
+ *   expiry: Expiry.days(1),
+ *   limits: [{ limit: 10_000_000n, token: ousd }],
+ *   scopes: [Scopes.tip20(ousd).transfer()],
+ * })
+ * ```
+ */
+export function from<const chainId extends number = number>(
+  value: Permissions<chainId>,
+): Permissions<chainId> {
+  return value
+}

package/src/client/Provider.ts

@@ -0,0 +1,18 @@
+/**
+ * The OAuth providers Tempo ID can offer.
+ * @module
+ */
+/** An OAuth provider's short name, as `Actions.provider.list` lists them. */
+export type Provider = 'google'
+
+/**
+ * Instantiates a {@link Provider}.
+ *
+ * @example
+ * ```ts
+ * const provider = Provider.from('google')
+ * ```
+ */
+export function from(value: Provider): Provider {
+  return value
+}

package/src/client/Step.ts

@@ -0,0 +1,24 @@
+/**
+ * A step a sign-in needs before it finishes, such as the SSO connection an address requires.
+ * @module
+ */
+
+/** A step that a sign-in needs before it finishes: the SSO connection that an address requires. */
+export type Step = {
+  /** The kind of step. */
+  type: 'sso'
+  /** Where `Actions.provider.signIn` sends the browser to take the step. */
+  url: string
+}
+
+/**
+ * Instantiates a {@link Step}.
+ *
+ * @example
+ * ```ts
+ * const step = Step.from({ type: 'sso', url })
+ * ```
+ */
+export function from(value: Step): Step {
+  return value
+}