@tempoxyz/id 0.0.0-pr-187.sha-eed04d3

package/dist/internal/Owner.d.ts

@@ -0,0 +1,146 @@
+/**
+ * The keys that own Tempo Accounts, and the contract that each kind of owner key implements, such as
+ * Privy wallets and wallet.tempo passkeys. `TempoAccount` lists the user's owners through every kind,
+ * and creates a first account through the first kind that creates owner keys in a realm. A new kind
+ * implements {@link Kind}, and joins `TempoAccount.kinds`.
+ * @module
+ */
+import type { Hex } from 'ox';
+import type { LocalAccount } from 'viem';
+import type { Account, AccountConfig } from 'viem/tempo';
+import type * as Auth from './Auth.js';
+import type * as ErrorResponse from './ErrorResponse.js';
+import type * as Realm from './Realm.js';
+import type * as Timing from './Timing.js';
+/** The deployment variables that owner kinds read. */
+export type Env = {
+    /** The RS256 private key, as PKCS #8 PEM, whose public half each Privy app trusts. Absent, no Privy wallet signs. */
+    PRIVY_JWT_PRIVATE_KEY?: string | undefined;
+    /** The `SECRET` variable, which encrypts the owner configurations of each realm. */
+    SECRET: string;
+};
+/**
+ * One kind of owner key. `load` reads the kind's configuration for the realms that a request
+ * reaches, once, and returns the operations that list and create the user's owner keys.
+ */
+export type Kind<type extends string = string, errors extends readonly ErrorResponse.Class[] = readonly ErrorResponse.Class[]> = {
+    /** The refusals that the kind's operations throw, such as an upstream service's failures. */
+    errors: errors;
+    /** Reads the kind's configuration for `realms`, and returns the operations on the user's owner keys. */
+    load: (c: Timing.measure.Context, options: Kind.load.Options) => Promise<Kind.Loaded<type>>;
+    /** The owner type in the API, such as `privy` or `webAuthn`. */
+    type: type;
+};
+export declare namespace Kind {
+    /** The operations on the user's owner keys of one kind, within the realms that `load` received. */
+    type Loaded<type extends string = string> = {
+        /**
+         * Returns a function that creates the user's first owner key in `realm`, or `undefined` when
+         * the kind creates none there, such as for a realm without the kind's configuration. Absent on
+         * a kind that only links owner keys created elsewhere. Such a kind lists from the database
+         * alone, since `TempoAccount.create` lists it again under the user's lock.
+         */
+        create?: ((realm: Realm.Realm) => ((c: Timing.measure.Context) => Promise<Owner<type>>) | undefined) | undefined;
+        /** Returns the user's owner keys of this kind, oldest first, and creates none. */
+        list: (c: Timing.measure.Context, options: Loaded.list.Options) => Promise<readonly Owner<type>[]>;
+    };
+    namespace Loaded {
+        namespace list {
+            type Options = {
+                /** The database or transaction to read. */
+                db: Realm.Database;
+            };
+        }
+    }
+    namespace load {
+        type Options = {
+            /** The database. */
+            db: Realm.Database;
+            /** The deployment variables. */
+            env: Env;
+            /** The realms that the request reaches, in order. */
+            realms: readonly Realm.Realm[];
+            /** The user's ID. */
+            userId: string;
+        };
+    }
+}
+/** A passkey that owns a Tempo Account, which signs only in a browser at its relying party. */
+export type Credential = {
+    /** The credential ID, base64url. */
+    id: string;
+    /** The uncompressed P256 public key, hex. */
+    publicKey: Hex.Hex;
+    /** The relying party ID of the passkey. */
+    rpId: string;
+};
+/** A key that owns one of the user's Tempo Accounts, with the account's realm. */
+export type Owner<type extends string = string> = {
+    /** The Tempo Account that the key owns. It cannot sign. */
+    account: Account.ConfigurableAccount<AccountConfig.Config>;
+    /** When the key was created, or linked when its creation time is unknown. */
+    createdAt: Date;
+    /**
+     * The passkey that signs for the key in the browser. Absent for a key that signs on the server,
+     * such as a Privy wallet.
+     */
+    credential?: Credential | undefined;
+    /** The account's realm. */
+    realm: Realm.Realm;
+    /**
+     * Returns the key as a Viem account that signs on the server. `undefined` for a key that signs
+     * only in the browser, such as a passkey.
+     */
+    signer: ((c: Timing.measure.Context, options: signer.Options) => Promise<LocalAccount>) | undefined;
+    /** The kind of the key, such as `privy` or `webAuthn`. */
+    type: type;
+};
+export declare namespace signer {
+    type Options = {
+        /** The request's Better Auth instance, which signs tokens that an upstream signer verifies. */
+        auth: Auth.Instance;
+    };
+}
+/**
+ * Instantiates an {@link Owner}.
+ *
+ * @example
+ * ```ts
+ * const owner = Owner.from({
+ *   account,
+ *   createdAt: key.createdAt,
+ *   credential: { id: key.id, publicKey: key.publicKey, rpId: key.rpId },
+ *   realm,
+ *   signer: undefined,
+ *   type: 'webAuthn',
+ * })
+ * ```
+ */
+export declare function from<const type extends string>(value: Owner<type>): Owner<type>;
+/**
+ * Instantiates a {@link Kind}.
+ *
+ * @example
+ * ```ts
+ * export const owner = Owner.kind({ errors: [], load, type: 'webAuthn' })
+ * ```
+ */
+export declare function kind<const type extends string, const errors extends readonly ErrorResponse.Class[]>(value: Kind<type, errors>): Kind<type, errors>;
+/**
+ * Merges lists of owners, each already oldest first, by creation time in seconds, the precision
+ * Privy records. A merge keeps the order of each list, so the first Privy wallet of a realm stays
+ * before its later wallets. An earlier list wins a tie.
+ */
+export declare function merge<const type extends string>(lists: readonly (readonly Owner<type>[])[]): readonly Owner<type>[];
+/**
+ * Takes the user's account lock until the transaction `tx` ends. `TempoAccount.create` and every
+ * kind that links owner keys take it, so a first account and a link for one user never interleave.
+ */
+export declare function lock(tx: Realm.Database, options: lock.Options): Promise<void>;
+export declare namespace lock {
+    type Options = {
+        /** The user's ID. */
+        userId: string;
+    };
+}
+//# sourceMappingURL=Owner.d.ts.map

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

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

package/dist/internal/Owner.js

@@ -0,0 +1,65 @@
+import { sql } from 'drizzle-orm';
+/**
+ * Instantiates an {@link Owner}.
+ *
+ * @example
+ * ```ts
+ * const owner = Owner.from({
+ *   account,
+ *   createdAt: key.createdAt,
+ *   credential: { id: key.id, publicKey: key.publicKey, rpId: key.rpId },
+ *   realm,
+ *   signer: undefined,
+ *   type: 'webAuthn',
+ * })
+ * ```
+ */
+export function from(value) {
+    return value;
+}
+/**
+ * Instantiates a {@link Kind}.
+ *
+ * @example
+ * ```ts
+ * export const owner = Owner.kind({ errors: [], load, type: 'webAuthn' })
+ * ```
+ */
+export function kind(value) {
+    return value;
+}
+/**
+ * Merges lists of owners, each already oldest first, by creation time in seconds, the precision
+ * Privy records. A merge keeps the order of each list, so the first Privy wallet of a realm stays
+ * before its later wallets. An earlier list wins a tie.
+ */
+export function merge(lists) {
+    const seconds = (date) => Math.floor(date.getTime() / 1000);
+    const heads = lists.map(() => 0);
+    const merged = [];
+    while (true) {
+        const next = lists.reduce((best, list, index) => {
+            const entry = list[heads[index]];
+            if (!entry)
+                return best;
+            if (best === undefined)
+                return index;
+            const current = lists[best][heads[best]];
+            return seconds(entry.createdAt) < seconds(current.createdAt)
+                ? index
+                : best;
+        }, undefined);
+        if (next === undefined)
+            return merged;
+        merged.push(lists[next][heads[next]]);
+        heads[next] = heads[next] + 1;
+    }
+}
+/**
+ * Takes the user's account lock until the transaction `tx` ends. `TempoAccount.create` and every
+ * kind that links owner keys take it, so a first account and a link for one user never interleave.
+ */
+export async function lock(tx, options) {
+    await tx.execute(sql `select pg_advisory_xact_lock(hashtextextended(${`tempo-account:${options.userId}`}, 0))`);
+}
+//# sourceMappingURL=Owner.js.map

package/dist/internal/Owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Owner.js","sourceRoot":"","sources":["../../src/internal/Owner.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAA;AA0HjC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAClB,KAAkB;IAElB,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAGlB,KAAyB;IACzB,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CACnB,KAA0C;IAE1C,MAAM,OAAO,GAAG,CAAC,IAAU,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAA;IACjE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAChC,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,OAAO,IAAI,EAAE,CAAC;QACZ,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YAClE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,CAAA;YACjC,IAAI,CAAC,KAAK;gBAAE,OAAO,IAAI,CAAA;YACvB,IAAI,IAAI,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAA;YACpC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAE,CAAC,KAAK,CAAC,IAAI,CAAE,CAAE,CAAA;YAC3C,OAAO,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;gBAC1D,CAAC,CAAC,KAAK;gBACP,CAAC,CAAC,IAAI,CAAA;QACV,CAAC,EAAE,SAAS,CAAC,CAAA;QACb,IAAI,IAAI,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QACrC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAE,CAAC,KAAK,CAAC,IAAI,CAAE,CAAE,CAAC,CAAA;QACxC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAE,GAAG,CAAC,CAAA;IAChC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,EAAkB,EAAE,OAAqB;IAClE,MAAM,EAAE,CAAC,OAAO,CACd,GAAG,CAAA,iDAAiD,iBAAiB,OAAO,CAAC,MAAM,EAAE,OAAO,CAC7F,CAAA;AACH,CAAC"}