@tempoxyz/id 0.0.0-stage → 0.0.1

package/dist/internal/SigningKey.d.ts

@@ -0,0 +1,126 @@
+/**
+ * The keys that sign Tempo ID's tokens: the JWT plugin's key options, and the rotation that
+ * `tempo-id admin rotate-key` runs on the `jwks` table. A rotation writes the row that the plugin
+ * writes when it creates a key, with Better Auth's key generation and encryption.
+ * @module
+ */
+import type { GenericEndpointContext } from '@better-auth/core';
+import { type Jwk } from 'better-auth/plugins/jwt';
+import type * as Cache from './Cache.js';
+import type * as Realm from './Realm.js';
+/**
+ * As many keys as the JWT plugin reads are live or in their grace period, so the plugin would not
+ * read a new key.
+ */
+export declare class FullError extends Error {
+    readonly name = "SigningKey.FullError";
+    constructor();
+}
+/** The table holds no signing key yet, so a rotation has no key to retire. */
+export declare class MissingError extends Error {
+    readonly name = "SigningKey.MissingError";
+    constructor();
+}
+/** The secret does not decrypt the current signing key, so the Worker could not use a new one. */
+export declare class SecretError extends Error {
+    readonly name = "SigningKey.SecretError";
+    constructor();
+}
+/**
+ * Seconds that `GET /oauth2/jwks` serves a key after it stops signing, so verifiers accept the tokens
+ * that it signed before. This is Better Auth's default, 30 days.
+ */
+export declare const gracePeriod: number;
+/**
+ * Seconds between a rotation and the first token that the new key signs. `GET /oauth2/jwks` serves
+ * the new key at once, and a verifier caches the response for 60 seconds at most. So a verifier that
+ * caches the key set, with a refetch cooldown such as jose's 30 seconds, holds the key before any
+ * token names it.
+ */
+export declare const publication: number;
+/**
+ * The most keys that the JWT plugin reads: Better Auth's default limit on a read. A rotation keeps
+ * the live keys and the keys in their grace period within it.
+ */
+export declare const capacity = 100;
+/** The JWT plugin's `jwks` options. RS256, since Privy and the existing verifiers accept it. */
+export declare const jwks: {
+    gracePeriod: number;
+    jwksPath: string;
+    keyPairConfig: {
+        alg: 'RS256';
+        modulusLength: number;
+    };
+};
+/**
+ * The JWT plugin's read of the `jwks` table: every live key, and every key in its grace period.
+ * Better Auth's own read returns any 100 rows, and a rotation backdates each new key's `createdAt`,
+ * so neither row order nor creation time can pick the keys once retired rows build up.
+ */
+export declare function adapter(options?: adapter.Options): {
+    getJwks: (ctx: GenericEndpointContext) => Promise<Jwk[]>;
+};
+export declare namespace adapter {
+    type Options = {
+        /**
+         * The isolate's cache of configuration rows, which holds the keys still encrypted. Absent, each
+         * read reads the database.
+         */
+        cache?: Cache.Cache | undefined;
+    };
+}
+/**
+ * Returns the public key that an ID token hint names in its `kid` header, as a key set, retired keys
+ * included, past the grace period too. Logout verifies the hint against it, since a session can
+ * outlast the grace period of the key that signed its ID token. A hint without a `kid`, or with an
+ * unknown one, returns an empty set. Tokens that grant access verify only against the keys that
+ * `GET /oauth2/jwks` serves.
+ */
+export declare function hintKeys(db: Realm.Database, options: hintKeys.Options): Promise<hintKeys.ReturnType>;
+export declare namespace hintKeys {
+    type Options = {
+        /** The ID token hint, whose `kid` header names its signing key. */
+        hint: string;
+    };
+    type ReturnType = {
+        /** Each public key, with its ID as `kid`. */
+        keys: (JsonWebKey & {
+            /** The key's ID, which each token that it signed names as `kid`. */
+            kid: string;
+        })[];
+    };
+}
+/**
+ * Adds a new signing key, which signs every token after the {@link publication} delay, and retires
+ * every earlier key that is still live at the end of that delay. `GET /oauth2/jwks` serves the new key
+ * at once, and serves each retired key until its grace period ends.
+ *
+ * Throws `MissingError` when no key exists, `SecretError` when `secret` does not decrypt the current
+ * key, and `FullError` when `capacity` keys are live or in their grace period.
+ */
+export declare function rotate(db: Realm.Database, options: rotate.Options): Promise<rotate.ReturnType>;
+export declare namespace rotate {
+    type Options = {
+        /** The deployment's `SECRET` variable, which encrypts each private key. */
+        secret: string;
+    };
+    type ReturnType = {
+        /** The new signing key. */
+        key: {
+            /** The key's ID, which each token names as `kid`. */
+            id: string;
+            /** When the key signs its first token, after the publication delay. */
+            signsFrom: Date;
+        };
+        /** The keys that the rotation retires, newest first. */
+        retired: readonly {
+            /** The key's ID. */
+            id: string;
+            /** When `GET /oauth2/jwks` stops serving the key. */
+            servedUntil: Date;
+            /** When the key signs its last token. */
+            signsUntil: Date;
+        }[];
+    };
+}
+//# sourceMappingURL=SigningKey.d.ts.map

package/dist/internal/SigningKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SigningKey.d.ts","sourceRoot":"","sources":["../../src/internal/SigningKey.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAG/D,OAAO,EAA2B,KAAK,GAAG,EAAE,MAAM,yBAAyB,CAAA;AAI3E,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AACxC,OAAO,KAAK,KAAK,KAAK,MAAM,YAAY,CAAA;AAExC;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAkB,IAAI,0BAAyB;IAE/C,cAIC;CACF;AAED,8EAA8E;AAC9E,qBAAa,YAAa,SAAQ,KAAK;IACrC,SAAkB,IAAI,6BAA4B;IAElD,cAIC;CACF;AAED,kGAAkG;AAClG,qBAAa,WAAY,SAAQ,KAAK;IACpC,SAAkB,IAAI,4BAA2B;IAEjD,cAIC;CACF;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAoB,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,WAAW,QAAS,CAAA;AAEjC;;;GAGG;AACH,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,gGAAgG;AAChG,eAAO,MAAM,IAAI;;;;QAGE,GAAG,EAAE,OAAO;QAAW,aAAa;;CACtD,CAAA;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,GAAE,OAAO,CAAC,OAAY;IAEjD,OAAO,QAAc,sBAAsB;EAiB9C;AAED,MAAM,CAAC,OAAO,WAAW,OAAO,CAAC;IAC/B,KAAK,OAAO,GAAG;QACb;;;WAGG;QACH,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,GAAG,SAAS,CAAA;KAChC,CAAA;CACF;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,KAAK,CAAC,QAAQ,EAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,GACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAuB9B;AAED,MAAM,CAAC,OAAO,WAAW,QAAQ,CAAC;IAChC,KAAK,OAAO,GAAG;QACb,mEAAmE;QACnE,IAAI,EAAE,MAAM,CAAA;KACb,CAAA;IAED,KAAK,UAAU,GAAG;QAChB,6CAA6C;QAC7C,IAAI,EAAE,CAAC,UAAU,GAAG;YAClB,oEAAoE;YACpE,GAAG,EAAE,MAAM,CAAA;SACZ,CAAC,EAAE,CAAA;KACL,CAAA;CACF;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,EAAE,EAAE,KAAK,CAAC,QAAQ,EAClB,OAAO,EAAE,MAAM,CAAC,OAAO,GACtB,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAgG5B;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,KAAK,OAAO,GAAG;QACb,2EAA2E;QAC3E,MAAM,EAAE,MAAM,CAAA;KACf,CAAA;IAED,KAAK,UAAU,GAAG;QAChB,2BAA2B;QAC3B,GAAG,EAAE;YACH,qDAAqD;YACrD,EAAE,EAAE,MAAM,CAAA;YACV,uEAAuE;YACvE,SAAS,EAAE,IAAI,CAAA;SAChB,CAAA;QACD,wDAAwD;QACxD,OAAO,EAAE,SAAS;YAChB,oBAAoB;YACpB,EAAE,EAAE,MAAM,CAAA;YACV,qDAAqD;YACrD,WAAW,EAAE,IAAI,CAAA;YACjB,yCAAyC;YACzC,UAAU,EAAE,IAAI,CAAA;SACjB,EAAE,CAAA;KACJ,CAAA;CACF"}

package/dist/internal/SigningKey.js

@@ -0,0 +1,221 @@
+import { getCurrentAdapter } from '@better-auth/core/context';
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto';
+import { generateExportedKeyPair } from 'better-auth/plugins/jwt';
+import { count, desc, eq, gt, isNull, or, sql } from 'drizzle-orm';
+import { decodeProtectedHeader } from 'jose';
+import * as Schema from '../app/db/schema.js';
+/**
+ * As many keys as the JWT plugin reads are live or in their grace period, so the plugin would not
+ * read a new key.
+ */
+export class FullError extends Error {
+    name = 'SigningKey.FullError';
+    constructor() {
+        super(`Too many signing keys: ${capacity} keys are live or in their 30-day grace period. Rotate again once the oldest grace period ends.`);
+    }
+}
+/** The table holds no signing key yet, so a rotation has no key to retire. */
+export class MissingError extends Error {
+    name = 'SigningKey.MissingError';
+    constructor() {
+        super('No signing key exists. Tempo ID creates the first key when it signs its first token.');
+    }
+}
+/** The secret does not decrypt the current signing key, so the Worker could not use a new one. */
+export class SecretError extends Error {
+    name = 'SigningKey.SecretError';
+    constructor() {
+        super("Invalid SECRET: it does not decrypt the current signing key. Set SECRET to the deployment's SECRET variable.");
+    }
+}
+/**
+ * Seconds that `GET /oauth2/jwks` serves a key after it stops signing, so verifiers accept the tokens
+ * that it signed before. This is Better Auth's default, 30 days.
+ */
+export const gracePeriod = 60 * 60 * 24 * 30;
+/**
+ * Seconds between a rotation and the first token that the new key signs. `GET /oauth2/jwks` serves
+ * the new key at once, and a verifier caches the response for 60 seconds at most. So a verifier that
+ * caches the key set, with a refetch cooldown such as jose's 30 seconds, holds the key before any
+ * token names it.
+ */
+export const publication = 5 * 60;
+/**
+ * The most keys that the JWT plugin reads: Better Auth's default limit on a read. A rotation keeps
+ * the live keys and the keys in their grace period within it.
+ */
+export const capacity = 100;
+/** The JWT plugin's `jwks` options. RS256, since Privy and the existing verifiers accept it. */
+export const jwks = {
+    gracePeriod,
+    jwksPath: '/oauth2/jwks',
+    keyPairConfig: { alg: 'RS256', modulusLength: 2048 },
+};
+/**
+ * The JWT plugin's read of the `jwks` table: every live key, and every key in its grace period.
+ * Better Auth's own read returns any 100 rows, and a rotation backdates each new key's `createdAt`,
+ * so neither row order nor creation time can pick the keys once retired rows build up.
+ */
+export function adapter(options = {}) {
+    return {
+        getJwks: async (ctx) => {
+            // `GET /oauth2/jwks` serves every committed key at once, such as a first key that another
+            // isolate created at the same time, so a verifier that refetches for an unknown `kid` finds it.
+            if (ctx.path === jwks.jwksPath)
+                return await readJwks(ctx);
+            // A new key signs only after the publication delay, and the entry lives a fifth of it, so
+            // the old key stops signing well before the rotation's `signsFrom`, though a read starts
+            // before the rotation commits. An empty table stays uncached, since the plugin then creates
+            // the first key.
+            if (!options.cache)
+                return await readJwks(ctx);
+            return [
+                ...(await options.cache.get(() => readJwks(ctx), ['signingKey.jwks'], {
+                    keep: (keys) => keys.length > 0,
+                    ttl: (publication / 5) * 1000,
+                })),
+            ];
+        },
+    };
+}
+/**
+ * Returns the public key that an ID token hint names in its `kid` header, as a key set, retired keys
+ * included, past the grace period too. Logout verifies the hint against it, since a session can
+ * outlast the grace period of the key that signed its ID token. A hint without a `kid`, or with an
+ * unknown one, returns an empty set. Tokens that grant access verify only against the keys that
+ * `GET /oauth2/jwks` serves.
+ */
+export async function hintKeys(db, options) {
+    // The header is read before the signature is checked, so a forged hint costs one indexed read.
+    const kid = (() => {
+        try {
+            return decodeProtectedHeader(options.hint).kid;
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    if (!kid)
+        return { keys: [] };
+    const rows = await db
+        .select()
+        .from(Schema.jwks)
+        .where(eq(Schema.jwks.id, kid))
+        .limit(1);
+    return {
+        keys: rows.map((row) => ({
+            ...JSON.parse(row.publicKey),
+            alg: row.alg ?? jwks.keyPairConfig.alg,
+            kid: row.id,
+        })),
+    };
+}
+/**
+ * Adds a new signing key, which signs every token after the {@link publication} delay, and retires
+ * every earlier key that is still live at the end of that delay. `GET /oauth2/jwks` serves the new key
+ * at once, and serves each retired key until its grace period ends.
+ *
+ * Throws `MissingError` when no key exists, `SecretError` when `secret` does not decrypt the current
+ * key, and `FullError` when `capacity` keys are live or in their grace period.
+ */
+export async function rotate(db, options) {
+    const { secret } = options;
+    return await db.transaction(async (tx) => {
+        // Serializes rotations, and keeps the Worker from creating a key between the read and the writes.
+        // Reads proceed, so the Worker signs with the current key until the commit.
+        await tx.execute(sql `lock table ${Schema.jwks} in share row exclusive mode`);
+        // The database's clock, which every deployment shares, so a skewed clock on the machine that
+        // runs the command cannot end the publication delay early. `clock_timestamp()` reads it after the
+        // lock, where `now()` would return the transaction's start and count the wait for the lock.
+        const [clock] = await tx
+            .select({
+            now: sql `(extract(epoch from clock_timestamp()) * 1000)::float8`,
+        })
+            .from(Schema.jwks)
+            .limit(1);
+        if (!clock)
+            throw new MissingError();
+        const now = new Date(Number(clock.now));
+        const signsFrom = new Date(now.getTime() + publication * 1000);
+        const live = await tx
+            .select()
+            .from(Schema.jwks)
+            .where(or(isNull(Schema.jwks.expiresAt), gt(Schema.jwks.expiresAt, now)))
+            .orderBy(desc(Schema.jwks.createdAt));
+        const [current] = live;
+        const oldest = live.at(-1);
+        if (!current || !oldest)
+            throw new MissingError();
+        // A key encrypted with another secret would fail every signature, so the rotation checks first.
+        const decrypted = await symmetricDecrypt({
+            data: JSON.parse(current.privateKey),
+            key: secret,
+        }).catch(() => undefined);
+        if (decrypted === undefined)
+            throw new SecretError();
+        // The read returns at most `capacity` rows, and a rotated key sorts last, so one more would hide it.
+        // The Worker applies the grace cutoff by its own clock, so the count also includes the keys whose
+        // grace period ended up to `publication` seconds ago, in case that clock is behind the database's.
+        const [served] = await tx
+            .select({ count: count() })
+            .from(Schema.jwks)
+            .where(or(isNull(Schema.jwks.expiresAt), gt(Schema.jwks.expiresAt, new Date(now.getTime() - (gracePeriod + publication) * 1000))));
+        if (served.count >= capacity)
+            throw new FullError();
+        const pair = await generateExportedKeyPair({ jwks });
+        const [key] = await tx
+            .insert(Schema.jwks)
+            .values({
+            alg: pair.alg,
+            // Better Auth signs with the live key of the latest `createdAt`. A `createdAt` before every
+            // live key's keeps the new key from signing until the earlier keys expire at `signsFrom`.
+            createdAt: new Date(oldest.createdAt.getTime() - 1),
+            id: crypto.randomUUID(),
+            // The JWT plugin stores the encrypted key as a JSON string.
+            privateKey: JSON.stringify(await symmetricEncrypt({
+                data: JSON.stringify(pair.privateWebKey),
+                key: secret,
+            })),
+            publicKey: JSON.stringify(pair.publicWebKey),
+        })
+            .returning({ id: Schema.jwks.id });
+        // A key that an earlier rotation already retires keeps its earlier expiry.
+        const retired = live.map((entry) => ({
+            expiresAt: entry.expiresAt && entry.expiresAt < signsFrom
+                ? entry.expiresAt
+                : signsFrom,
+            id: entry.id,
+        }));
+        for (const entry of retired)
+            await tx
+                .update(Schema.jwks)
+                .set({ expiresAt: entry.expiresAt })
+                .where(eq(Schema.jwks.id, entry.id));
+        return {
+            key: { id: key.id, signsFrom },
+            retired: retired.map((entry) => ({
+                id: entry.id,
+                servedUntil: new Date(entry.expiresAt.getTime() + gracePeriod * 1000),
+                signsUntil: entry.expiresAt,
+            })),
+        };
+    });
+}
+/** Reads every live key, and every key in its grace period, past the cache. */
+async function readJwks(ctx) {
+    return await (await getCurrentAdapter(ctx.context.adapter)).findMany({
+        limit: capacity,
+        model: 'jwks',
+        sortBy: { direction: 'desc', field: 'createdAt' },
+        where: [
+            { connector: 'OR', field: 'expiresAt', value: null },
+            {
+                connector: 'OR',
+                field: 'expiresAt',
+                operator: 'gt',
+                value: new Date(Date.now() - gracePeriod * 1000),
+            },
+        ],
+    });
+}
+//# sourceMappingURL=SigningKey.js.map

package/dist/internal/SigningKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SigningKey.js","sourceRoot":"","sources":["../../src/internal/SigningKey.ts"],"names":[],"mappings":"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"}

package/dist/internal/TempoAccount.d.ts

@@ -0,0 +1,181 @@
+import { z } from 'zod';
+import type { Env } from './Env.js';
+import * as ErrorResponse from './ErrorResponse.js';
+import * as Owner from './Owner.js';
+import type * as Realm from './Realm.js';
+declare const ForeignAccountError_base: {
+    new (options: ErrorResponse.define.Options): {
+        message: string;
+        stack?: string;
+        cause?: unknown;
+        readonly res?: Response;
+        readonly status: import("hono/utils/http-status").ContentfulStatusCode;
+        getResponse(): Response;
+        readonly name: string;
+        readonly response: Omit<{
+            error: string;
+            error_description: string;
+            error_uri: string;
+            field?: string | undefined;
+            meta?: Readonly<Record<string, string | number>> | undefined;
+            reason: string;
+            request_id?: string | undefined;
+        }, "error" | "reason"> & {
+            error: "access_denied";
+            reason: "foreign_account";
+        };
+    };
+    readonly reason: "foreign_account";
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/** The request names a Tempo Account that is not one of the user's in the app's realms. */
+export declare class ForeignAccountError extends ForeignAccountError_base {
+    readonly name = "TempoAccount.ForeignAccountError";
+    constructor(options: ForeignAccountError.Options);
+}
+export declare namespace ForeignAccountError {
+    type Options = {
+        /** The address that the request named. */
+        account: string;
+        /** The request field that named the address. Defaults to `account`. */
+        field?: string | undefined;
+    };
+}
+/**
+ * The kinds of owner keys, in the order that breaks a tie in creation time: a passkey comes before a
+ * Privy wallet created in the same second, and a Privy wallet before a secp256k1 key. The first kind
+ * that creates keys in a realm creates a user's first account there, so a realm with a Privy app
+ * creates Privy wallets even where it also holds secp256k1 owners.
+ */
+export declare const kinds: readonly [Owner.Kind<"webAuthn", readonly []>, Owner.Kind<"privy", readonly [typeof ErrorResponse.RateLimitedError, typeof ErrorResponse.UpstreamUnavailableError]>, Owner.Kind<"secp256k1", readonly []>];
+/**
+ * A request's context. Once {@link middleware} ran, it holds the owner keys that the request listed,
+ * so a request lists each user's keys in the same realms once.
+ */
+export type Context = Owner.Context & {
+    /** The request's variables. */
+    var: {
+        /** The owner keys that the request listed. Absent, as in the CLI, each list reads again. */
+        ownerLists?: Lists | undefined;
+    };
+};
+/**
+ * The owner keys that one request listed, by user and realms, as each kind's list in the order of
+ * {@link kinds}. {@link middleware} creates it for each request, and {@link forget} empties it after a
+ * write that changes a user's owner keys.
+ */
+export type Lists = Map<string, Promise<readonly (readonly Owner.Owner<Type>[])[]>>;
+/** A user's Tempo Account, as the API returns it. */
+export type TempoAccount = z.output<typeof schema.tempoAccount>;
+/** The owner type in the API, such as `privy`, `secp256k1`, or `webAuthn`. */
+export type Type = (typeof kinds)[number]['type'];
+/** Zod schemas for Tempo Accounts as the API returns them. */
+export declare namespace schema {
+    /** A realm, with its display name. */
+    const realm: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    /** A Tempo Account, with its configuration and its realm. */
+    const tempoAccount: z.ZodObject<{
+        address: z.ZodTemplateLiteral<`0x${string}`>;
+        config: z.ZodObject<{
+            chainId: z.ZodOptional<z.ZodNumber>;
+            owners: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+                owner: z.ZodTemplateLiteral<`0x${string}`>;
+                type: z.ZodEnum<{
+                    privy: "privy";
+                    secp256k1: "secp256k1";
+                    webAuthn: "webAuthn";
+                }>;
+                weight: z.ZodNumber;
+            }, z.core.$strip>>>;
+            salt: z.ZodTemplateLiteral<`0x${string}`>;
+            threshold: z.ZodNumber;
+            version: z.ZodTemplateLiteral<`0x${string}`>;
+        }, z.core.$strip>;
+        realm: z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, as {@link held} does, and creates
+ * one in the first realm for a user with none, when a kind creates keys in that realm. On a
+ * deployment with configurable accounts, the new account is configurable from its creation. A user with a
+ * linked owner key, such as a wallet.tempo passkey, receives none. Concurrent calls, through apps
+ * whose realms overlap, and a link at the same time create one account. No database connection
+ * stays open while a kind creates the key.
+ */
+export declare function create(c: Context, options: create.Options): Promise<readonly Owner.Owner<Type>[]>;
+export declare namespace create {
+    type Options = list.Options;
+    /** The refusals `create` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    const errors: readonly [typeof ErrorResponse.RateLimitedError, typeof ErrorResponse.UpstreamUnavailableError];
+}
+/**
+ * Returns the keys that own the user's Tempo Accounts in `realms`, oldest first, and creates none.
+ * Each kind reads its keys in parallel.
+ */
+export declare function held(c: Context, options: held.Options): Promise<readonly Owner.Owner<Type>[]>;
+export declare namespace held {
+    type Options = list.Options;
+    /** The refusals `held` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    const errors: readonly [typeof ErrorResponse.RateLimitedError, typeof ErrorResponse.UpstreamUnavailableError];
+}
+/**
+ * Returns the user's Tempo Accounts in `realms`, oldest first, as the API returns them, and creates
+ * none. Their owners are those that {@link held} returns.
+ */
+export declare function list(c: Context, options: list.Options): Promise<readonly TempoAccount[]>;
+export declare namespace list {
+    type Options = {
+        /**
+         * The ID of the chain that the request acts on. On a chain that `CONFIGURABLE_ACCOUNTS` names,
+         * each owner carries its configurable view, whose address is the account's there. Absent, or on
+         * any other chain, each key acts as its account.
+         */
+        chainId?: number | undefined;
+        /** The database. */
+        db: Realm.Database;
+        /** The deployment variables that the kinds read. */
+        env: Owner.Env;
+        /** The realms that the request reaches, in order. The first holds a user's first account. */
+        realms: readonly Realm.Realm[];
+        /** The user's ID. */
+        userId: string;
+    };
+    /** The refusals `list` throws, which `ErrorResponse.handle` responds with: each kind's failures. */
+    const errors: readonly [typeof ErrorResponse.RateLimitedError, typeof ErrorResponse.UpstreamUnavailableError];
+}
+/**
+ * Empties the owner keys that the request listed. Call it after a write that changes a user's owner
+ * keys outside {@link create}, such as a passkey's link or registration, so a later list in the same
+ * request reads them again.
+ */
+export declare function forget(c: Context): void;
+/**
+ * Sets `c.var.ownerLists` to an empty {@link Lists} for the request, or to the lists of the page's
+ * request for an in-process call of its loader.
+ */
+export declare const middleware: import("hono").MiddlewareHandler<Env, string, {}, Response>;
+/**
+ * Returns the owner of `account` that signs its keys: a cloud wallet when the account has one, since
+ * Tempo ID signs with it, or else its first owner. A configuration sorts its owners by address, so
+ * the first owner alone does not name it.
+ */
+export declare function signer(account: TempoAccount): {
+    owner: `0x${string}`;
+    type: "privy" | "secp256k1" | "webAuthn";
+    weight: number;
+} | undefined;
+/**
+ * Returns the Tempo Account that `owner` owns, as the API returns it. A configurable account carries
+ * its configuration on the configurable-accounts chain, with each owner's kind.
+ */
+export declare function serialize(owner: Owner.Owner): TempoAccount;
+export {};
+//# sourceMappingURL=TempoAccount.d.ts.map

package/dist/internal/TempoAccount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TempoAccount.d.ts","sourceRoot":"","sources":["../../src/internal/TempoAccount.ts"],"names":[],"mappings":"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"}