@tempoxyz/id 0.0.0-stage → 0.0.1

package/dist/internal/Realm.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Realms: the sets of Tempo Accounts that apps reach. The `realms` table holds each realm, and its
+ * owner configurations live in their own tables: `realm_passkeys` for its passkey relying party,
+ * `realm_privy` for its Privy app, and `realm_secp256k1` for the secp256k1 owners that Tempo ID
+ * holds. The `app_realms` table maps each OAuth app to its realms, in order. An app without rows
+ * reaches the `default` realm.
+ * @module
+ */
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
+import { z } from 'zod';
+import * as Schema from '../app/db/schema.js';
+import * as Cache from './Cache.js';
+import type * as Privy from './Privy.js';
+/** An app names the realm, so the realm cannot be removed. */
+export declare class InUseError extends Error {
+    readonly name = "Realm.InUseError";
+    constructor(options: {
+        id: string;
+    });
+}
+/** A realm ID, a name, a Privy app, or a list of realms is not valid. */
+export declare class InvalidError extends Error {
+    readonly name = "Realm.InvalidError";
+}
+/** No OAuth app has the client ID. */
+export declare class NotFoundAppError extends Error {
+    readonly name = "Realm.NotFoundAppError";
+    constructor(options: {
+        clientId: string;
+    });
+}
+/** No realm has the ID. */
+export declare class NotFoundError extends Error {
+    readonly name = "Realm.NotFoundError";
+    constructor(options: {
+        id: string;
+    });
+}
+/** A realm with the ID exists. */
+export declare class TakenError extends Error {
+    readonly name = "Realm.TakenError";
+    constructor(options: {
+        id: string;
+    });
+}
+/** Another realm holds the passkey relying party. A passkey belongs to exactly one relying party. */
+export declare class TakenPasskeysError extends Error {
+    readonly name = "Realm.TakenPasskeysError";
+    constructor(options: {
+        rpId: string;
+    });
+}
+/** Another realm holds the Privy app. Realms that shared one would list the same accounts. */
+export declare class TakenPrivyAppError extends Error {
+    readonly name = "Realm.TakenPrivyAppError";
+    constructor(options: {
+        appId: string;
+    });
+}
+/** A database with Tempo ID's tables, through any Postgres driver. */
+export type Database = PgDatabase<PgQueryResultHKT, typeof Schema>;
+/** One set of Tempo Accounts, which only the apps that name it reach. */
+export type Realm = {
+    /** The realm ID, such as `default` or `tempo-cash`. */
+    id: string;
+    /** The display name, which labels the realm's accounts, such as `Tempo Cash`. */
+    name: string;
+    /** The passkey relying party whose passkeys own accounts in the realm. `undefined` when the realm has none. */
+    passkeys: {
+        /** The relying party ID, a registrable domain such as `tempo.xyz`. */
+        rpId: string;
+    } | undefined;
+    /** The Privy app that holds the realm's Privy owners. `undefined` when the realm has none. */
+    privy: {
+        /** The Privy app ID. */
+        appId: string;
+    } | undefined;
+    /** Whether Tempo ID holds the realm's secp256k1 owners itself, as in the suites and local development. */
+    secp256k1: boolean;
+};
+/** The ID of the realm that every app without rows in `app_realms` reaches. */
+export declare const defaultId = "default";
+/** Zod schemas for the values that define realms. */
+export declare namespace schema {
+    /** A realm ID, in lowercase kebab case. */
+    const id: z.ZodString;
+    /** A realm, as `add` receives it. */
+    const realm: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    /** A realm's passkey relying party, as `setPasskeys` receives it. */
+    const passkeys: z.ZodObject<{
+        realmId: z.ZodString;
+        rpId: z.ZodString;
+    }, z.core.$strip>;
+    /** A realm's Privy app, as `setPrivy` receives it. */
+    const privy: z.ZodObject<{
+        appId: z.ZodString;
+        appSecret: z.ZodString;
+        realmId: z.ZodString;
+    }, z.core.$strip>;
+    /** An app's realms, in order, each named once. */
+    const realms: z.ZodArray<z.ZodString>;
+}
+/**
+ * Adds a realm without owner configurations, and returns it.
+ *
+ * Throws `InvalidError` for an invalid value, and `TakenError` when the ID exists.
+ */
+export declare function add(db: Database, options: add.Options): Promise<Realm>;
+export declare namespace add {
+    type Options = {
+        /** The realm ID, in lowercase kebab case, such as `tempo-cash`. */
+        id: string;
+        /** The display name, such as `Tempo Cash`. */
+        name: string;
+    };
+}
+/**
+ * Returns the realms of the app with `clientId`, in order, in one query. The first realm holds a
+ * user's first account. An app without rows, or an unknown client ID, reaches the `default` realm.
+ */
+export declare function forApp(db: Database, options: forApp.Options): Promise<readonly Realm[]>;
+export declare namespace forApp {
+    type Options = {
+        /** The OAuth app's client ID. */
+        clientId: string;
+    };
+}
+/**
+ * Returns the realms that a request reaches for the app with `clientId`, in order. A request that
+ * names no app reaches the `default` realm. So does a browser page that names an app from an origin
+ * none of the app's redirect URIs has, since a page cannot read another app's accounts. A native app
+ * sends no `Origin`, and Tempo ID's own pages send `own`. The request's cache holds each read by
+ * client ID, never by the `Origin` that a caller chooses.
+ */
+export declare function forRequest(c: Cache.read.Context, options: forRequest.Options): Promise<readonly Realm[]>;
+export declare namespace forRequest {
+    type Options = {
+        /** The client ID that the request names, if any. */
+        clientId?: string | undefined;
+        /** The database. */
+        db: Database;
+        /** The request's `Origin`, if any. */
+        origin?: string | undefined;
+        /** Tempo ID's own origin. */
+        own: string;
+    };
+}
+/**
+ * Instantiates a {@link Realm}.
+ *
+ * @example
+ * ```ts
+ * const realm = Realm.from({
+ *   id: 'tempo-cash',
+ *   name: 'Tempo Cash',
+ *   privy: { appId: 'cm…' },
+ *   secp256k1: false,
+ * })
+ * ```
+ */
+export declare function from(value: Realm): Realm;
+/** Returns the realm with `id`. Throws `NotFoundError` when no realm has it. */
+export declare function get(db: Database, options: get.Options): Promise<Realm>;
+export declare namespace get {
+    type Options = {
+        /** The realm ID, such as `tempo-cash`. */
+        id: string;
+    };
+}
+/** Returns every realm: `default` first, then the others by ID. */
+export declare function list(db: Database): Promise<readonly Realm[]>;
+/**
+ * Returns the Privy apps of `realms`, by realm ID, with each app secret decrypted with `secret`. A
+ * realm without a Privy app has no entry. Reads every realm in one query. The request's cache holds
+ * the encrypted rows, so each request decrypts the secrets again, and no plaintext secret outlives it.
+ */
+export declare function privyApps(c: Cache.read.Context, options: privyApps.Options): Promise<ReadonlyMap<string, Privy.App>>;
+export declare namespace privyApps {
+    type Options = {
+        /** The database. */
+        db: Database;
+        /** The realms whose Privy apps to read. */
+        realms: readonly Realm[];
+        /** The `SECRET` variable, which encrypts each app secret. */
+        secret: string;
+    };
+}
+/**
+ * Removes the realm with `id`, with its owner configurations.
+ *
+ * Throws `InvalidError` for an invalid ID or `default`, `NotFoundError` when no realm has the ID,
+ * and `InUseError` while an app names the realm.
+ */
+export declare function remove(db: Database, options: remove.Options): Promise<void>;
+export declare namespace remove {
+    type Options = {
+        /** The realm ID, such as `tempo-cash`. */
+        id: string;
+    };
+}
+/**
+ * Sets the realms of the app with `clientId`, in order, and returns them. An empty list removes the
+ * app's rows, so the app reaches the `default` realm.
+ *
+ * Throws `InvalidError` for an invalid ID or a repeated realm, `NotFoundAppError` when no OAuth app
+ * has the client ID, and `NotFoundError` when no realm has one of the IDs.
+ */
+export declare function setForApp(db: Database, options: setForApp.Options): Promise<readonly Realm[]>;
+export declare namespace setForApp {
+    type Options = {
+        /** The OAuth app's client ID. */
+        clientId: string;
+        /** The realm IDs, in order, such as `['default', 'tempo-cash']`. Empty for the `default` realm alone. */
+        realms: readonly string[];
+    };
+}
+/**
+ * Sets the passkey relying party of the realm with `realmId`, and returns the realm. It replaces an
+ * earlier relying party. Passkeys of that relying party then own accounts in the realm.
+ *
+ * Throws `InvalidError` for an invalid value, `NotFoundError` when no realm has the ID, and
+ * `TakenPasskeysError` when another realm holds the relying party.
+ */
+export declare function setPasskeys(db: Database, options: setPasskeys.Options): Promise<Realm>;
+export declare namespace setPasskeys {
+    type Options = {
+        /** The realm ID, such as `default`. */
+        realmId: string;
+        /** The relying party ID, a registrable domain such as `tempo.xyz`. */
+        rpId: string;
+    };
+}
+/**
+ * Sets the Privy app that holds the Privy owners of the realm with `realmId`, and returns the realm.
+ * It replaces an earlier Privy app. The row holds the app secret encrypted with `secret`.
+ *
+ * Throws `InvalidError` for an invalid value, `NotFoundError` when no realm has the ID, and
+ * `TakenPrivyAppError` when another realm holds the Privy app.
+ */
+export declare function setPrivy(db: Database, options: setPrivy.Options): Promise<Realm>;
+export declare namespace setPrivy {
+    type Options = {
+        /** The Privy app ID. */
+        appId: string;
+        /** The Privy app secret, which the row holds only encrypted. */
+        appSecret: string;
+        /** The realm ID, such as `tempo-cash`. */
+        realmId: string;
+        /** The `SECRET` variable, which encrypts the app secret. */
+        secret: string;
+    };
+}
+/**
+ * Sets whether Tempo ID holds the secp256k1 owners of the realm with `realmId`, and returns the
+ * realm. The realm then creates a user's first account with a key that Tempo ID holds. Turning it
+ * off keeps the realm's stored keys, and lists none of them.
+ *
+ * Throws `InvalidError` for an invalid ID, and `NotFoundError` when no realm has the ID.
+ */
+export declare function setSecp256k1(db: Database, options: setSecp256k1.Options): Promise<Realm>;
+export declare namespace setSecp256k1 {
+    type Options = {
+        /** Whether Tempo ID holds the realm's secp256k1 owners. */
+        enabled: boolean;
+        /** The realm ID, such as `default`. */
+        realmId: string;
+    };
+}
+/**
+ * Returns `realms` with the relying party that each one signs in with. The `default` realm without a
+ * `realm_passkeys` row signs in with passkeys of the registrable domain of `origin`, such as
+ * `tempo.xyz` for `https://id.tempo.xyz`, so every deployment offers passkeys without configuration. A row replaces that relying party. When another realm's row holds
+ * the host or a parent domain of it, `default` has none, since that realm's passkeys sign in at the
+ * same origin. The request's cache holds that lookup by domain.
+ */
+export declare function withDefaults(c: Cache.read.Context, options: withDefaults.Options): Promise<readonly Realm[]>;
+export declare namespace withDefaults {
+    type Options = {
+        /** The database. */
+        db: Database;
+        /** Tempo ID's origin, such as `https://id.tempo.xyz`. */
+        origin: string;
+        /** The realms that a request reaches, in order. */
+        realms: readonly Realm[];
+    };
+}
+//# sourceMappingURL=Realm.d.ts.map

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

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