@jskit-ai/oidc-issuer-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @jskit-ai/oidc-issuer-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An accounts hub for a JSKIT app: one sign-in for all of an owner's apps. The
+hub is an OpenID Connect issuer that runs as its own project on a domain of its
+own. People create one account there (email and password, optional "Continue
+with Google" with the owner's own Google client); the owner approves each app
+that wants to use those accounts.
+
+Start from the **JSKIT · Accounts hub** template (seed-jskit branch
+`accounts-hub`): it has the sign-in, account and admin pages, the tests and a
+quick start. To build a hub by hand, follow the `auth/accounts-hub` pattern.
+
+```sh
+npm install @jskit-ai/oidc-issuer-core @jskit-ai/database-runtime-mysql
+```
+
+The settings that matter, in the order a new hub needs them:
+
+| Name | Meaning |
+|---|---|
+| `OIDC_HUB_OWNER_EMAIL` | The owner's email. That account, once confirmed, opens Apps, People and Setup. |
+| `OIDC_HUB_REGISTRATION_TOKEN` | At least 24 random characters. Every app presents it to register. |
+| `OIDC_HUB_SECRET` | At least 32 random bytes; required in production, never changed once set. |
+| `APP_PUBLIC_URL` | The hub's https address, which is its issuer. Required in production. |
+| `OIDC_HUB_EMAIL_FROM` with `RESEND_API_KEY` or `SMTP_URL` | The owner's own sender. Required in production. |
+| `OIDC_HUB_DEV_ORIGIN_PATTERNS` | Optional `https://` globs of development addresses approved automatically. |
+
+A missing or wrong setting stops the hub with one sentence that names it.
+
+Apps connect with `@jskit-ai/auth-provider-oidc-core` and two values: the hub's
+address and its registration token.
+
+Commands, run from the hub project: `npx jskit-oidc-issuer keys rotate` and
+`npx jskit-oidc-issuer import-accounts --in accounts.jsonl [--apply]` (a dry run
+unless `--apply`).
+
+Guides: "Run an accounts hub" and "Sign in through an OIDC issuer" in the JSKIT
+guide (`packages/agent-docs/site/guide/app-setup/`).

package/bin/jskit-oidc-issuer.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { createKnexMigrationConfigFromApp } from "@jskit-ai/database-runtime/server/knexMigrationConfig";
+import createKnex from "knex";
+import { resolveHubConfig } from "../src/server/config.js";
+import { describeImport, importAccounts } from "../src/server/importAccounts.js";
+import { runPreviewIdentityCommand } from "../src/server/previewIdentity.js";
+import { createSigningKeyStore } from "../src/server/signingKeys.js";
+
+const USAGE = `Usage:
+  jskit-oidc-issuer keys rotate
+  jskit-oidc-issuer import-accounts --in <file> [--apply]
+  jskit-oidc-issuer preview-identity
+
+Run from the hub application's folder; it reads the same .env and database settings.`;
+
+function loadDotEnv() {
+  try {
+    process.loadEnvFile?.(".env");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+}
+
+async function withKnex(work) {
+  const config = await createKnexMigrationConfigFromApp({ client: process.env.DB_CLIENT || "mysql2" });
+  const knex = createKnex({ client: config.client, connection: config.connection });
+  try {
+    return await work(knex);
+  } finally {
+    await knex.destroy();
+  }
+}
+
+async function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === "preview-identity") {
+    return runPreviewIdentityCommand();
+  }
+  loadDotEnv();
+  if (command === "keys" && rest[0] === "rotate") {
+    const config = resolveHubConfig(process.env, { appRoot: process.cwd() });
+    const kid = await withKnex((knex) => createSigningKeyStore(knex, { secret: config.secret }).rotate());
+    console.log(`New signing key ${kid} is active. The previous key keeps verifying for two hours. A running hub picks it up within a minute.`);
+    return 0;
+  }
+  if (command === "import-accounts") {
+    const inIndex = rest.indexOf("--in");
+    const file = inIndex >= 0 ? rest[inIndex + 1] : "";
+    if (!file || !existsSync(path.resolve(file))) {
+      console.error("Name the exported accounts file with --in <file>.");
+      return 1;
+    }
+    const apply = rest.includes("--apply");
+    const result = await withKnex((knex) => importAccounts({ knex, text: readFileSync(path.resolve(file), "utf8"), apply }));
+    console.log(describeImport(result, { apply }));
+    return result.conflicts.length > 0 ? 2 : 0;
+  }
+  console.error(USAGE);
+  return 1;
+}
+
+process.exitCode = await main(process.argv.slice(2)).catch((error) => {
+  console.error(error?.message || String(error));
+  return 1;
+});