@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/Decorator.ts

@@ -0,0 +1,444 @@
+/**
+ * The `tempoId` Viem client extension, which adds Tempo ID's actions as `client.auth`.
+ *
+ * @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 * 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 { TempoAccount } from './TempoAccount.js'
+import type { User } from './User.js'
+
+/** A client created without `account: Auth.account()`. */
+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 needs for `chainId`. */
+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, and the
+ * overtaken result is never returned.
+ */
+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`, with one instance
+ * on the client's chain. Each sign-in sets the client's account, and `signOut` empties it at once.
+ * An overtaken sign-in throws {@link SupersededError}. The extension throws
+ * {@link ChainRequiredError} without a chain, and {@link AccountRequiredError} without 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 a change to the client's account. If a newer change completed first, each operation
+     * throws {@link SupersededError}, except `apply(undefined)`. A `signedIn` refusal empties the
+     * account.
+     */
+    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(
+          authorization: Pick<Authorization, 'account' | 'key'> | undefined,
+        ) {
+          if (version !== started) {
+            if (authorization) throw await superseded()
+            return
+          }
+          state.account = authorization?.account
+          state.key = authorization?.key
+          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
+            state.key = undefined
+            version++
+          }
+          throw error
+        },
+        async settle(
+          result: Authorization | Actions.redirect.handleCallback.WithoutKey,
+        ) {
+          if ('account' in result) return this.apply(result)
+          // 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
+          state.key = undefined
+          version++
+        },
+      }
+    }
+
+    /** Runs a passkey sign-in, and sets the client's account, unless it returns the email step. */
+    const passkeySignIn = async <
+      result extends Actions.passkey.signIn.ReturnType<number, boolean>,
+    >(
+      fn: () => Promise<result>,
+    ) => {
+      const change = begin()
+      const result = await fn().catch(change.fail)
+      if ('step' in result) await change.check()
+      else await change.settle(result.authorization)
+      return result
+    }
+
+    return {
+      auth: {
+        account: {
+          get: (options) => Actions.account.get(auth, options),
+          // The client's own key registers before the upgrade, as its own account sends.
+          upgrade(options = {}) {
+            const key = options.key ?? state.key
+            if (!key && !options.account) throw new Auth.SignedOutError()
+            // The client's account signs for its own key, also one that the app supplied, which
+            // carries no material.
+            const accessKey =
+              options.accessKey ?? (options.key ? undefined : state.account)
+            return Actions.account.upgrade(auth, { ...options, accessKey, key })
+          },
+        },
+        async authorize(options = {}) {
+          const change = begin()
+          const result = await Actions.authorize(auth, options)
+          // Without a session, the client stops signing as the user it last authorized.
+          if (result) await change.settle(result.authorization)
+          else await change.apply(undefined)
+          return result
+        },
+        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)
+                return authorization
+              },
+            }
+          },
+        },
+        email: {
+          sendCode: (options) => Actions.email.sendCode(auth, options),
+          async signIn(options) {
+            const change = begin()
+            const result = await Actions.email
+              .signIn(auth, options)
+              .catch(change.fail)
+            await change.settle(result.authorization)
+            return result
+          },
+        },
+        instance: auth,
+        oauth: {
+          introspect: (options) => Actions.oauth.introspect(auth, options),
+          jwks: () => Actions.oauth.jwks(auth),
+          userInfo: (options) => Actions.oauth.userInfo(auth, options),
+        },
+        passkey: {
+          available: () => Actions.passkey.available(auth),
+          prepare(options = {}) {
+            const prepared = Actions.passkey.prepare(auth, options)
+            return {
+              available: prepared.available,
+              signIn: (signInOptions = {}) =>
+                passkeySignIn(() => prepared.signIn(signInOptions)),
+            }
+          },
+          signIn: (options = {}) =>
+            passkeySignIn(() => Actions.passkey.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
+          },
+          prefetch: () => Actions.redirect.prefetch(auth),
+          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
+          state.key = key
+          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
+          state.key = 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. `chainId` is the client's chain, the default of each
+   * member's `permissions.chainId`.
+   */
+  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: (
+          options?: Actions.account.get.Options,
+        ) => Promise<Actions.account.get.ReturnType>
+        /**
+         * `Actions.account.upgrade`, with `key` defaulting to the key that the client signs with, so
+         * the key keeps signing after the upgrade. Throws `Auth.SignedOutError` while signed out,
+         * unless `account` names the account.
+         */
+        upgrade: (
+          options?: Actions.account.upgrade.Options,
+        ) => Promise<TempoAccount>
+      }
+      /**
+       * `Actions.authorize`, which sets the client's account, or empties it for `key: false` 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 the device grant. */
+      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 `key: false`
+         * or a refusal marked `signedIn`.
+         */
+        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 that the members pass to `Actions`. */
+      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.available`. */
+        available: () => Promise<boolean>
+        /**
+         * `Actions.passkey.prepare`, whose handle's `signIn` sets the client's account as
+         * `auth.passkey.signIn` does.
+         */
+        prepare: <
+          const id extends number = chainId,
+          const key extends boolean = true,
+        >(
+          options?: Actions.passkey.prepare.Options<id, key>,
+        ) => Actions.passkey.prepare.ReturnType<id, key>
+        /**
+         * `Actions.passkey.signIn`, which sets the client's account as `auth.email.signIn` does,
+         * unless it returns a step.
+         */
+        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 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. Later calls on the page load return the first call's 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.prefetch`. */
+        prefetch: () => Promise<Actions.redirect.prefetch.ReturnType>
+        /** `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. Throws `Key.AccessKeyRequiredError` for a key without
+       * material and no `accessKey`.
+       */
+      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 pending sign-in.
+       */
+      signOut: () => Promise<void>
+    }
+  }
+}

package/src/client/Key.ts

@@ -0,0 +1,137 @@
+/**
+ * An app's access key on a user's Tempo Account, as the app stores it.
+ * @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, and any other a
+ * secp256k1 private key. A key that 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 that 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
+    }
+  | {}
+>
+
+/** `toAccount` received a key without material, and no `accessKey`. */
+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}, and fills an absent `chainId` from the key authorization.
+ *
+ * @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 key's chain. Defaults to the key authorization's chain. */
+    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 for its Tempo Account. Viem attaches the
+ * authorization to transactions until the chain registers the key. Throws
+ * {@link AccessKeyRequiredError} for a key without material and no `accessKey`.
+ *
+ * @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 that the app supplied to the sign-in, which signs for a key without material. */
+    accessKey?: Account.Account | undefined
+  }
+}

package/src/client/Pending.ts

@@ -0,0 +1,45 @@
+/**
+ * A sign-in redirect in progress, which an app keeps until Tempo ID redirects back.
+ * @module
+ */
+import type * as Key from './Key.js'
+
+/**
+ * A redirect that authorizes a new access key, with the key's material. {@link WithoutKey}
+ * authorizes none.
+ */
+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. The code exchange repeats it. */
+  redirectUri: string
+  /** The value that the callback must echo, so a forged callback fails. */
+  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,41 @@
+/**
+ * What an app's access key may do.
+ * @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 its defaults. `chainId` types the authorization's `key.chainId`.
+ */
+export type Permissions<chainId extends number = number> = {
+  /** The key's chain, such as `tempoTestnet.id`. Defaults to the instance's `chainId`. */
+  chainId?: chainId | undefined
+  /** Unix seconds, such as Viem's `Expiry.days(1)`. Defaults to a year from the request. */
+  expiry?: number | undefined
+  /**
+   * How much of each token the key may spend, in base units, in total or per `period` seconds.
+   * Defaults to about $1,000 of each token that `scopes` call, 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/Storage.ts

@@ -0,0 +1,29 @@
+/**
+ * Where a redirect keeps its state until Tempo ID redirects back.
+ * @module
+ */
+/** Keeps a redirect's state, as structured-clone storage such as IndexedDB does. */
+export type Storage = {
+  /** Reads the value at `key`, or `undefined`. */
+  getItem: (key: string) => Promise<unknown>
+  /** Deletes the value at `key`. */
+  removeItem: (key: string) => Promise<void>
+  /** Writes `value` at `key`, without serializing it. */
+  setItem: (key: string, value: unknown) => Promise<void>
+}
+
+/**
+ * Instantiates a {@link Storage}.
+ *
+ * @example
+ * ```ts
+ * const storage = Storage.from({
+ *   getItem: (key) => idb.get(key),
+ *   removeItem: (key) => idb.del(key),
+ *   setItem: (key, value) => idb.set(key, value),
+ * })
+ * ```
+ */
+export function from(value: Storage): Storage {
+  return value
+}