@tempoxyz/id 0.0.0-stage → 0.0.1

package/src/client/Auth.ts

@@ -0,0 +1,267 @@
+/**
+ * Creates the Tempo ID instance that every action in `Actions` takes.
+ *
+ * @example
+ * ```ts
+ * import { Actions, Auth } from '@tempoxyz/id/client'
+ * import { Expiry, Scopes } from 'viem/tempo'
+ * import { tempo } from 'viem/tempo/chains'
+ * import * as Tokens from 'viem/tokens'
+ *
+ * // OUSD has its mainnet address on every Tempo chain.
+ * const ousd = Tokens.ousd(tempo.id).address
+ *
+ * const auth = Auth.create({ clientId: 'client_…', dev: true })
+ *
+ * const authorization = await Actions.authorize(auth, {
+ *   permissions: {
+ *     expiry: Expiry.days(1),
+ *     limits: [{ limit: 10_000_000n, token: ousd }],
+ *     scopes: [Scopes.tip20(ousd).transfer()],
+ *   },
+ * })
+ * ```
+ * @module
+ */
+import type { Account as ViemAccount } from 'viem/tempo'
+import { tempo, tempoTestnet } from 'viem/tempo/chains'
+import * as AccountState from './internal/account.js'
+import type { Storage } from './Storage.js'
+
+/**
+ * The account of a client extended with `tempoId`, which each sign-in sets and sign-out empties.
+ * Reading it while signed out throws {@link SignedOutError}.
+ */
+export type Account = ViemAccount.AccessKeyAccount & {
+  /** The account's state, which only the `tempoId` extension reads. */
+  readonly [AccountState.key]: AccountState.State
+}
+
+/** A Tempo ID instance, which every action takes. */
+export type Auth = {
+  /** The chain of the app's keys, unless an action's `permissions` names another. */
+  chainId: number
+  /** The app's client ID, from its registration as an OAuth app. */
+  clientId: string
+  /** The app's client secret. Only a backend holds one. */
+  clientSecret?: string | undefined
+  /** Calls Tempo ID. Defaults to the global `fetch`. */
+  fetch?: typeof globalThis.fetch | undefined
+  /** Where Tempo ID redirects back to. Defaults to the page's origin in a browser. */
+  redirectUri?: string | undefined
+  /** The scopes of the app's tokens, always with `openid` and `email`. */
+  scope: string
+  /** Where `Actions.redirect.start` keeps its state, unserialized. Defaults to IndexedDB. */
+  storage?: Storage | undefined
+  /** Where Tempo ID runs, such as `https://id.tempo.xyz`. */
+  url: string
+}
+
+/** An action received a `challenge` with `key: false`. A challenge rides in a key. */
+export class ChallengeWithoutKeyError extends Error {
+  override readonly name = 'Auth.ChallengeWithoutKeyError'
+
+  constructor() {
+    super(
+      'A challenge rides in the key authorization, so a sign-in with `key: false` takes none. Remove `challenge`, or request a key.',
+    )
+  }
+}
+
+/** A request that Tempo ID refused. */
+export class RequestError extends Error {
+  override readonly name = 'Auth.RequestError'
+  /** The OAuth error code, such as `invalid_authorization_details`. */
+  readonly code: string
+  /** The request field at fault, as a dotted path. */
+  readonly field: string | undefined
+  /** The values that the refusal compared, such as `maximum`. Base units are decimal strings. */
+  readonly meta: Readonly<Record<string, number | string>> | undefined
+  /** A stable name for the refusal, to branch on. */
+  readonly reason: RequestError.Reason | undefined
+  /** Whether a sign-in verified before the refusal, so the user is signed in. */
+  readonly signedIn: boolean
+  /** The HTTP status, or 0 for a request without a response. */
+  readonly status: number
+  /** The page that explains the error. */
+  readonly uri: string | undefined
+
+  constructor(options: RequestError.Options) {
+    super(options.message, { cause: options.cause })
+    this.code = options.code
+    this.field = options.field
+    this.meta = options.meta
+    this.reason = options.reason
+    this.signedIn = options.signedIn ?? false
+    this.status = options.status
+    this.uri = options.uri
+  }
+}
+
+export declare namespace RequestError {
+  type Options = {
+    /** The error that caused this one. */
+    cause?: unknown
+    /** The OAuth `error`. */
+    code: string
+    /** The request field at fault. */
+    field?: string | undefined
+    /** The `error_description`. */
+    message: string
+    /** The values that the refusal compared. */
+    meta?: Readonly<Record<string, number | string>> | undefined
+    /** The refusal's stable name. Absent from the issuer's own errors. */
+    reason?: Reason | undefined
+    /** Whether a sign-in verified before the refusal. Defaults to `false`. */
+    signedIn?: boolean | undefined
+    /** The HTTP status, or 0 without a response. */
+    status: number
+    /** The `error_uri`. */
+    uri?: string | undefined
+  }
+
+  /** Each refusal's stable name, as `docs/errors.md` explains. */
+  type Reason =
+    | 'already_decided'
+    | 'authorization_expired'
+    | 'body_too_large'
+    | 'challenge_not_permitted'
+    | 'config_conflict'
+    | 'configurable_accounts_disabled'
+    | 'cross_site_request'
+    | 'duplicate_limit'
+    | 'duplicate_scope'
+    | 'empty_limits'
+    | 'empty_scopes'
+    | 'expiry_exceeds_maximum'
+    | 'expiry_passed'
+    | 'foreign_account'
+    | 'foreign_origin'
+    | 'invalid_chain'
+    | 'invalid_code'
+    | 'invalid_expiry'
+    | 'invalid_field'
+    | 'invalid_id_token_hint'
+    | 'invalid_origin'
+    | 'invalid_period'
+    | 'invalid_public_key'
+    | 'invalid_recipients'
+    | 'limit_exceeds_maximum'
+    | 'logout_not_permitted'
+    | 'malformed_body'
+    | 'missing_code_challenge'
+    | 'missing_key'
+    | 'missing_permissions'
+    | 'missing_recipients'
+    | 'not_configurable'
+    | 'owner_exists'
+    | 'passkey_limit'
+    | 'passkey_link_expired'
+    | 'passkey_not_permitted'
+    | 'post_logout_redirect_not_permitted'
+    | 'rate_limited'
+    | 'reauthentication_required'
+    | 'rejected'
+    | 'scope_without_limit'
+    | 'session_changed'
+    | 'session_required'
+    | 'sign_up_not_permitted'
+    | 'unexpected'
+    | 'unknown_code'
+    | 'unknown_endpoint'
+    | 'unsupported_call'
+    | 'unsupported_token'
+    | 'upgrade_required'
+    | 'upstream_unavailable'
+    | 'webauthn_rejected'
+    | 'webauthn_required'
+}
+
+/** A client's {@link Account} read before a sign-in set it, or after sign-out emptied it. */
+export class SignedOutError extends Error {
+  override readonly name = 'Auth.SignedOutError'
+
+  constructor() {
+    super(
+      "The client's account is signed out. Sign in through `client.auth` before sending.",
+    )
+  }
+}
+
+/**
+ * Creates the account of a client extended with `tempoId`. Until a sign-in sets it, reading it
+ * throws {@link SignedOutError}. Each client needs its own, since the account signs as one user.
+ *
+ * @example
+ * ```ts
+ * const client = createClient({
+ *   account: Auth.account(),
+ *   chain: tempoTestnet,
+ * }).extend(tempoId({ clientId: 'client_…' }))
+ * ```
+ */
+export function account(): Account {
+  const state: AccountState.State = { account: undefined, key: undefined }
+  // Viem reads a client's account only when an action runs, through property reads, `in` checks,
+  // and spreads. Each trap reads through to the account that the latest sign-in set.
+  const proxy = new Proxy(
+    {},
+    {
+      get(_, key) {
+        if (key === AccountState.key) return state
+        if (state.account) return Reflect.get(state.account, key)
+        // Promise resolution, serialization, and inspection probe these, which must not throw.
+        if (typeof key === 'symbol' || key === 'then' || key === 'toJSON')
+          return undefined
+        throw new SignedOutError()
+      },
+      getOwnPropertyDescriptor(_, key) {
+        if (!state.account) return undefined
+        const descriptor = Reflect.getOwnPropertyDescriptor(state.account, key)
+        // A proxy may report a property its empty target lacks only as configurable.
+        return descriptor && { ...descriptor, configurable: true }
+      },
+      has: (_, key) =>
+        key === AccountState.key ||
+        (state.account !== undefined && Reflect.has(state.account, key)),
+      ownKeys: () => (state.account ? Reflect.ownKeys(state.account) : []),
+    },
+  )
+  return proxy as Account
+}
+
+/**
+ * Creates a Tempo ID instance.
+ *
+ * @example
+ * ```ts
+ * const auth = Auth.create({ clientId: 'client_…' })
+ * ```
+ */
+export function create(options: create.Options): Auth {
+  const { chainId, dev, scope = 'offline_access', url, ...rest } = options
+  // Every authorization reads the user from the ID token, which needs `openid` and `email`.
+  const scopes = scope.split(' ').filter(Boolean)
+  return {
+    ...rest,
+    chainId: chainId ?? (dev ? tempoTestnet.id : tempo.id),
+    scope: [...new Set(['openid', 'email', ...scopes])].join(' '),
+    url: url ?? defaultUrl,
+  }
+}
+
+export declare namespace create {
+  type Options = Omit<Auth, 'chainId' | 'scope' | 'url'> & {
+    /** The chain of the app's keys. Defaults to Tempo mainnet, or Tempo testnet with `dev`. */
+    chainId?: number | undefined
+    /** Whether to use Tempo testnet. Defaults to `false`. */
+    dev?: boolean | undefined
+    /** Scopes beyond `openid` and `email`. Defaults to `offline_access`, for a refresh token. */
+    scope?: string | undefined
+    /** Defaults to `https://id.tempo.xyz`. */
+    url?: string | undefined
+  }
+}
+
+/** Where Tempo ID runs unless `create` receives a `url`. */
+const defaultUrl = 'https://id.tempo.xyz'

package/src/client/Authorization.ts

@@ -0,0 +1,34 @@
+/**
+ * What every sign-in returns.
+ * @module
+ */
+import type * as Key from './Key.js'
+import type { Tokens } from './Tokens.js'
+import type { User } from './User.js'
+
+/**
+ * The tokens, the access key, and the user. `chainId` types `key.chainId`, as a literal when
+ * `permissions` names one.
+ */
+export type Authorization<chainId extends number = number> = Tokens & {
+  /** The user's Tempo Account, as a Viem account that signs with the app's access key. */
+  account: ReturnType<typeof Key.toAccount>
+  /** The same key as data, which `Key.toAccount` rebuilds into `account`. */
+  key: Key.Key<chainId>
+  /** The signed-in user, from the ID token. */
+  user: User
+}
+
+/**
+ * Instantiates a {@link Authorization}.
+ *
+ * @example
+ * ```ts
+ * const authorization = Authorization.from({ ...saved, account: Key.toAccount(saved.key) })
+ * ```
+ */
+export function from<chainId extends number = number>(
+  value: Authorization<chainId>,
+): Authorization<chainId> {
+  return value
+}