@tempoxyz/id 0.0.0-pr-192.sha-ffc93d6 → 0.0.0-pr-331.sha-b603cbf

package/README.md

@@ -64,6 +64,8 @@ npx tempo-id init my-id --from "Tempo ID <noreply@id.example.com>" --url https:/
 
 [Self-hosting](docs/self-hosting.md) covers the database, secrets, migrations, and deploys.
 
+An optional second Worker runs the Admin API and its dashboard through `Admin.create` from `@tempoxyz/id/admin`, on a host that the public cannot reach, with an `authorize` function of the deployment's own. [Admin API](docs/development/admin.md) describes Tempo's deployment of it.
+
 ## Playgrounds
 
 [`playgrounds/`](playgrounds/README.md) holds one app per flow, deployed beside `https://id.tempo.xyz`.
@@ -109,6 +111,7 @@ Sign in at the printed URL with a test address, such as `tempo-id-test+dev@examp
 pnpm i             # install dependencies
 pnpm dev           # start Tempo ID, the playgrounds, and a local chain on OrbStack
 pnpm dev:app       # serve the app from src/app with Void, with HMR, the email inbox, and the dev toolbar
+pnpm dev:admin     # serve the admin app from src/admin/app with Void, with HMR, signed in as a local admin
 pnpm dev:id        # build the app, and serve apps/id with wrangler dev
 pnpm env:pull      # populate .env variables from 1Password
 pnpm build         # build the package and the app

package/dist/Admin.d.ts

@@ -0,0 +1,51 @@
+import type * as Env from './admin/Env.js';
+/** An option of `Admin.create` is absent or invalid. */
+export declare class InvalidOptionError extends Error {
+    readonly name = "Admin.InvalidOptionError";
+}
+/** The employee or service that a request acts as. */
+export type Actor = Env.Actor;
+/**
+ * Returns the admin Worker's handler, which serves the admin app's pages, such as the dashboard,
+ * and the Admin API: OAuth app registration and
+ * operation. `authorize` runs before every request, so a deployment without it never starts. Serve
+ * it on a host that the public cannot reach, never on Tempo ID's own.
+ *
+ * ```ts
+ * import { env } from 'cloudflare:workers'
+ * import { Admin } from '@tempoxyz/id/admin'
+ *
+ * export default Admin.create({
+ *   authorize: async (request) =>
+ *     (await verify(request)) ?? new Response(null, { status: 401 }),
+ *   db: env.HYPERDRIVE,
+ * })
+ * ```
+ *
+ * @throws {InvalidOptionError} When an option is absent or invalid, so the Worker fails to start.
+ */
+export declare function create(options: create.Options): create.ReturnType;
+export declare namespace create {
+    type Options = {
+        /**
+         * Decides whether a request may reach the Admin API, before every route. Returns the actor,
+         * whose `sub` the audit logs record, or a `Response` that refuses the request, such as a 401.
+         * It verifies the request itself, such as a Cloudflare Access assertion, and fails closed.
+         */
+        authorize: Env.Authorize;
+        /**
+         * A Hyperdrive binding, such as `env.HYPERDRIVE`, or `{ connectionString }`, to the database of
+         * the Tempo ID deployment that the API operates.
+         */
+        db: {
+            /** The Postgres connection string. */
+            connectionString: string;
+        };
+    };
+    type ReturnType = {
+        /** Serves a request to the Worker. */
+        fetch: (request: Request, env: Record<string, unknown>, ctx: unknown) => Promise<Response>;
+    };
+    type ErrorType = InvalidOptionError;
+}
+//# sourceMappingURL=Admin.d.ts.map

package/dist/Admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Admin.d.ts","sourceRoot":"","sources":["../src/Admin.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,KAAK,GAAG,MAAM,gBAAgB,CAAA;AAE1C,wDAAwD;AACxD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,8BAA6B;CACpD;AAED,sDAAsD;AACtD,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAA;AAE7B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAgBjE;AAED,MAAM,CAAC,OAAO,WAAW,MAAM,CAAC;IAC9B,KAAK,OAAO,GAAG;QACb;;;;WAIG;QACH,SAAS,EAAE,GAAG,CAAC,SAAS,CAAA;QACxB;;;WAGG;QACH,EAAE,EAAE;YACF,sCAAsC;YACtC,gBAAgB,EAAE,MAAM,CAAA;SACzB,CAAA;KACF,CAAA;IAED,KAAK,UAAU,GAAG;QAChB,sCAAsC;QACtC,KAAK,EAAE,CACL,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,GAAG,EAAE,OAAO,KACT,OAAO,CAAC,QAAQ,CAAC,CAAA;KACvB,CAAA;IAED,KAAK,SAAS,GAAG,kBAAkB,CAAA;CACpC"}

package/dist/Admin.js

@@ -0,0 +1,52 @@
+/**
+ * Tempo ID's Admin API as a Cloudflare Worker, on a host of its own, from the deployment's options.
+ * @module
+ */
+import handlers from '#admin-app';
+/** An option of `Admin.create` is absent or invalid. */
+export class InvalidOptionError extends Error {
+    name = 'Admin.InvalidOptionError';
+}
+/**
+ * Returns the admin Worker's handler, which serves the admin app's pages, such as the dashboard,
+ * and the Admin API: OAuth app registration and
+ * operation. `authorize` runs before every request, so a deployment without it never starts. Serve
+ * it on a host that the public cannot reach, never on Tempo ID's own.
+ *
+ * ```ts
+ * import { env } from 'cloudflare:workers'
+ * import { Admin } from '@tempoxyz/id/admin'
+ *
+ * export default Admin.create({
+ *   authorize: async (request) =>
+ *     (await verify(request)) ?? new Response(null, { status: 401 }),
+ *   db: env.HYPERDRIVE,
+ * })
+ * ```
+ *
+ * @throws {InvalidOptionError} When an option is absent or invalid, so the Worker fails to start.
+ */
+export function create(options) {
+    validate(options);
+    const { authorize, db } = options;
+    // The built admin app reads its settings from the bindings under these names. A Hyperdrive
+    // binding's connection string is read for each request.
+    const bindings = (env) => ({
+        ...env,
+        ADMIN_AUTHORIZE: authorize,
+        ADMIN_DATABASE_URL: db.connectionString,
+    });
+    return {
+        fetch: (request, env, ctx) => handlers.fetch(request, bindings(env), ctx),
+    };
+}
+/** Throws when an option is absent or invalid, since bindings and functions escape type checks. */
+function validate(options) {
+    const { authorize, db } = options;
+    if (typeof authorize !== 'function')
+        throw new InvalidOptionError('Missing `authorize`. Pass a function that verifies each request, such as a Cloudflare Access assertion, and returns its actor or a refusal.');
+    // `db` can be a Hyperdrive binding, whose connection string is read only within a request.
+    if (typeof db !== 'object' || db === null)
+        throw new InvalidOptionError('Missing `db`. Pass a Hyperdrive binding, such as `env.HYPERDRIVE`, or `{ connectionString }`.');
+}
+//# sourceMappingURL=Admin.js.map

package/dist/Admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Admin.js","sourceRoot":"","sources":["../src/Admin.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,QAAQ,MAAM,YAAY,CAAA;AAGjC,wDAAwD;AACxD,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAG,0BAA0B,CAAA;CACpD;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,MAAM,CAAC,OAAuB;IAC5C,QAAQ,CAAC,OAAO,CAAC,CAAA;IAEjB,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,OAAO,CAAA;IAEjC,2FAA2F;IAC3F,wDAAwD;IACxD,MAAM,QAAQ,GAAG,CAAC,GAA4B,EAAE,EAAE,CAAC,CAAC;QAClD,GAAG,GAAG;QACN,eAAe,EAAE,SAAS;QAC1B,kBAAkB,EAAE,EAAE,CAAC,gBAAgB;KACxC,CAAC,CAAA;IAEF,OAAO;QACL,KAAK,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC;KAC1E,CAAA;AACH,CAAC;AAgCD,mGAAmG;AACnG,SAAS,QAAQ,CAAC,OAAuB;IACvC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,GAAG,OAAO,CAAA;IAEjC,IAAI,OAAO,SAAS,KAAK,UAAU;QACjC,MAAM,IAAI,kBAAkB,CAC1B,6IAA6I,CAC9I,CAAA;IACH,2FAA2F;IAC3F,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,IAAI;QACvC,MAAM,IAAI,kBAAkB,CAC1B,+FAA+F,CAChG,CAAA;AACL,CAAC"}

package/dist/admin/Env.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The Hono environment of the Admin API, which `Admin.create` serves on a host of its own.
+ * @module
+ */
+import type { Context } from 'hono';
+import type * as Env_ from '../internal/Env.js';
+import type * as Realm from '../internal/Realm.js';
+/** The employee or service that a request acts as, from the deployment's `authorize`. */
+export type Actor = {
+    /**
+     * The actor's email address, which the dashboard shows to the actor alone. Logs never record it.
+     * Absent, the dashboard shows `sub`.
+     */
+    email?: string | undefined;
+    /** A stable, opaque ID of the actor, which audit logs record. Never an email address. */
+    sub: string;
+};
+/** Decides whether a request may reach the Admin API. */
+export type Authorize = (request: Request) => Promise<Actor | Response>;
+/** The bindings and variables of an admin request. */
+export type Env = {
+    /** The values that `Admin.create` adds to the Worker's bindings. */
+    Bindings: {
+        /** The deployment's authorization, from `Admin.create`. */
+        ADMIN_AUTHORIZE: Authorize;
+        /** The Postgres connection string, read for each request, from `Admin.create`. */
+        ADMIN_DATABASE_URL: string;
+        /**
+         * Renders the admin app's page of `c`'s request through TanStack Start. Absent, as in the
+         * Admin API without its app's build, a page path responds with `unknown_endpoint`.
+         */
+        ADMIN_PAGES?: ((c: Context<Env>) => Promise<Response>) | undefined;
+    };
+    /** The values that middleware sets on `c.var`. */
+    Variables: Pick<Env_.Variables, 'refusal' | 'requestId' | 'timing'> & {
+        /** The actor that `authorize` returned. */
+        actor: Actor;
+        /** The request's database client, which the admin app connects for the app routes. */
+        db: Realm.Database;
+    };
+};
+//# sourceMappingURL=Env.d.ts.map

package/dist/admin/Env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Env.d.ts","sourceRoot":"","sources":["../../src/admin/Env.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAA;AACnC,OAAO,KAAK,KAAK,IAAI,MAAM,oBAAoB,CAAA;AAC/C,OAAO,KAAK,KAAK,KAAK,MAAM,sBAAsB,CAAA;AAElD,yFAAyF;AACzF,MAAM,MAAM,KAAK,GAAG;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,yFAAyF;IACzF,GAAG,EAAE,MAAM,CAAA;CACZ,CAAA;AAED,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,KAAK,GAAG,QAAQ,CAAC,CAAA;AAEvE,sDAAsD;AACtD,MAAM,MAAM,GAAG,GAAG;IAChB,oEAAoE;IACpE,QAAQ,EAAE;QACR,2DAA2D;QAC3D,eAAe,EAAE,SAAS,CAAA;QAC1B,kFAAkF;QAClF,kBAAkB,EAAE,MAAM,CAAA;QAC1B;;;WAGG;QACH,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,SAAS,CAAA;KACnE,CAAA;IACD,kDAAkD;IAClD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC,GAAG;QACpE,2CAA2C;QAC3C,KAAK,EAAE,KAAK,CAAA;QACZ,sFAAsF;QACtF,EAAE,EAAE,KAAK,CAAC,QAAQ,CAAA;KACnB,CAAA;CACF,CAAA"}

package/dist/admin/Env.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Env.js.map

package/dist/admin/Env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Env.js","sourceRoot":"","sources":["../../src/admin/Env.ts"],"names":[],"mappings":""}

package/dist/admin/app/client/.assetsignore

@@ -0,0 +1,2 @@
+wrangler.json
+.dev.vars