kempo-oauth 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# kempo-oauth
 
-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.
+Sign in and register with Google, GitHub, Facebook, X and Microsoft on a [kempo](https://github.com/dustinpoissant/kempo) site. The client ids and secrets are managed in the admin portal; the buttons appear under the login and register forms.
+
+## Install
+
+```bash
+npm install kempo-oauth
+```
+
+Then install it from the admin portal (Extensions). Client secrets are stored as kempo `secret` settings, so `SETTINGS_ENCRYPTION_KEY` must be set in the site's environment first — generate one with `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` and back it up.
+
+### Sites created before the slots existed
+
+The buttons are pushed into two slots on kempo's login and register pages: `login-form-after` and `register-form-after`. Pages copied from a kempo older than that don't have them. Add one line just after the closing `</form>` of each:
+
+```html
+<!-- public/login/index.page.html -->
+<location name="login-form-after" />
+
+<!-- public/register/index.page.html -->
+<location name="register-form-after" />
+```
+
+## Connecting a provider
+
+Open **Sign-in Providers** in the admin portal. Each provider card shows the **redirect URI** to give the provider (`https://your-site/oauth/api/callback/<provider>`), a link to the provider's developer console, and fields for the client id and secret. A provider is shown on the login page only when it is switched on **and** has both.
+
+Behind a proxy that changes the scheme or host, set **Site address** so the redirect URI is built from the public address rather than the one this process sees.
+
+| Provider | Gives an email? | Email trusted to join an existing account? |
+|---|---|---|
+| Google | yes | yes, when Google says it is verified |
+| GitHub | yes (primary verified) | yes |
+| Facebook | yes | **no** — Facebook never says it was confirmed |
+| Microsoft | yes | **no** — a directory can hold any address |
+| X | **no** | — |
+
+## How accounts are matched
+
+- A returning person is found by the provider's **id**, never the email.
+- A first-time sign-in whose email matches an existing account is connected to it **only if the provider vouches for the email** (and "Connect … with the same email" is on). Otherwise the visitor is told an account exists and to sign in the way they signed up.
+- If that existing account never verified its email, its password is invalidated and its sessions ended before connecting (guards against someone pre-registering your address).
+- Otherwise a new account is created, honouring `allow_registration` and `require_email_verification`. Its password is random and unknown; the person can set one with "forgot password".
+- X shares no email, so its accounts get an `…@oauth.invalid` placeholder. A site requiring verified emails cannot offer X.
+
+## Security notes
+
+Authorization code flow with PKCE (S256) and a per-attempt `state`, held in a short-lived HttpOnly `lax` cookie scoped to `/oauth/api`. Nothing is stored server-side mid-flow, and provider access tokens are discarded after reading the profile. Redirect targets (`next`, "after sign-in") must be paths on this site. Failures return to the login page as a short code, never text from the provider.
+
+## Permissions
+
+`oauth:view` (see connected accounts), `oauth:unlink` (disconnect one), `oauth:settings` (providers and secrets). Groups: `kempo-oauth:viewer`, `kempo-oauth:administrator`.
+
+## Adding a provider
+
+One file in `server/providers/` (contract documented at the top of `server/providers/index.js`) plus its settings in `kempo-config.json`; a test fails until both exist. Another kempo (CMS) extension can call `registerProvider` from `kempo-oauth/sdk`.
+
+## Out of scope
+
+Apple (needs a signed-JWT client secret), Discord, LinkedIn and others (each is one provider file), OpenID discovery, refresh tokens / calling providers on a user's behalf, and a "connect another provider" button on the account page.
+
+## Development
+
+```bash
+docker compose up -d                      # test database on port 5445
+npm run link:local
+DATABASE_URL=postgresql://kempo:kempo@localhost:5445/kempo_oauth_test npx drizzle-kit push --force
+DATABASE_URL=postgresql://kempo:kempo@localhost:5445/kempo_oauth_test SETTINGS_ENCRYPTION_KEY=$(openssl rand -hex 32) npm test
+```
+
+Check for `(SKIPPED)` in the output: database suites skip themselves, and a skip reads as a pass. They also refuse any database not named `*_test`.

package/admin/components/LinkedAccounts.js

@@ -0,0 +1,134 @@
+import ShadowComponent from '/kempo-ui/components/ShadowComponent.js';
+import '/kempo-ui/components/Icon.js';
+import '/kempo-ui/components/Spinner.js';
+import { html } from '/kempo-ui/lit-all.min.js';
+import { deleteAccount, getAccounts } from '/oauth/sdk.js';
+
+/*
+  Who has signed in with which provider.
+
+  A row whose user no longer exists is shown as such rather than hidden: it is harmless (the next
+  sign-in with that provider replaces it), but an admin looking at "Unknown user" wants to be told
+  it is a deleted account and not a bug.
+*/
+
+const PAGE_SIZE = 25;
+
+export default class LinkedAccounts extends ShadowComponent {
+  static properties = {
+    result: { type: Object, state: true },
+    providers: { type: Array, state: true },
+    provider: { type: String, state: true },
+    offset: { type: Number, state: true },
+    error: { type: String, state: true },
+  };
+
+  constructor(){
+    super();
+    this.result = null;
+    this.providers = [];
+    this.provider = '';
+    this.offset = 0;
+    this.error = '';
+  }
+
+  /*
+    Lifecycle
+  */
+
+  connectedCallback(){
+    super.connectedCallback();
+    this.load();
+  }
+
+  /*
+    Data
+  */
+
+  load = async () => {
+    const [error, result] = await getAccounts({ limit: PAGE_SIZE, offset: this.offset, provider: this.provider });
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.error = '';
+    this.result = result;
+    this.providers = result.providers;
+  };
+
+  filter = event => {
+    this.provider = event.target.value;
+    this.offset = 0;
+    this.load();
+  };
+
+  page = step => {
+    this.offset = Math.max(this.offset + step * PAGE_SIZE, 0);
+    this.load();
+  };
+
+  disconnect = async account => {
+    if(!confirm(`Disconnect ${account.provider} from ${account.userName || 'this user'}? They keep their account.`)) return;
+
+    const [error] = await deleteAccount(account.id);
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.load();
+  };
+
+  /*
+    Rendering
+  */
+
+  render(){
+    if(!this.result) return this.error ? html`<p class="tc-danger">${this.error}</p>` : html`<k-spinner></k-spinner>`;
+
+    const { accounts, total, offset } = this.result;
+
+    return html`
+      ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
+
+      ${this.providers.length ? html`
+        <label>
+          <span class="d-b">Provider</span>
+          <select @change=${this.filter}>
+            <option value="" ?selected=${!this.provider}>All</option>
+            ${this.providers.map(provider => html`<option value=${provider.name} ?selected=${provider.name === this.provider}>${provider.label}</option>`)}
+          </select>
+        </label>
+      ` : ''}
+
+      ${accounts.length ? html`
+        <div class="table-wrapper">
+          <table>
+            <thead>
+              <tr><th>Provider</th><th>User</th><th>Email from provider</th><th>Last sign-in</th><th></th></tr>
+            </thead>
+            <tbody>
+              ${accounts.map(account => html`
+                <tr>
+                  <td>${account.provider}</td>
+                  <td>${account.userExists ? html`${account.userName}<br /><span class="small tc-muted">${account.userEmail}</span>` : html`<span class="tc-muted">Deleted user</span>`}</td>
+                  <td>${account.email || html`<span class="tc-muted">none shared</span>`}</td>
+                  <td>${new Date(account.lastLoginAt).toLocaleString()}</td>
+                  <td><button class="link tc-danger" title="Disconnect" @click=${() => this.disconnect(account)}><k-icon name="delete"></k-icon></button></td>
+                </tr>
+              `)}
+            </tbody>
+          </table>
+        </div>
+        <p class="small tc-muted">
+          ${offset + 1}–${offset + accounts.length} of ${total}
+          <button class="link" ?disabled=${offset === 0} @click=${() => this.page(-1)}>Previous</button>
+          <button class="link" ?disabled=${offset + accounts.length >= total} @click=${() => this.page(1)}>Next</button>
+        </p>
+      ` : html`<p class="tc-muted">Nobody has signed in with a provider yet.</p>`}
+    `;
+  }
+}
+
+customElements.define('k-oauth-accounts', LinkedAccounts);

package/admin/components/ProviderSettings.js

@@ -0,0 +1,257 @@
+import ShadowComponent from '/kempo-ui/components/ShadowComponent.js';
+import '/kempo-ui/components/Icon.js';
+import '/kempo-ui/components/Spinner.js';
+import { html } from '/kempo-ui/lit-all.min.js';
+import { getSettings, saveSettings } from '/oauth/sdk.js';
+
+/*
+  Connecting the site to sign-in providers.
+
+  Three things on this screen are load-bearing and none of them is the form itself:
+
+  - **The redirect URI.** Copy-pasteable, one per provider, beside the fields it goes with. A site
+    whose redirect URI is wrong gets as far as the provider's own error page, which names neither
+    this site nor the cause, and the person looking at it is not the person who can fix it.
+  - **The status line.** "Active", "Off" and "Incomplete" are different things and the third is the
+    one that surprises people: a provider with an id and no secret is simply not offered, and
+    nothing on the login page says why.
+  - **Blank means unchanged.** A secret cannot be read back, so its field is always empty. Saving
+    the form after changing something else must not wipe the secret, and clearing one on purpose is
+    a separate, explicit button.
+*/
+export default class ProviderSettings extends ShadowComponent {
+  static properties = {
+    data: { type: Object, state: true },
+    edits: { type: Object, state: true },
+    saving: { type: Boolean, state: true },
+    error: { type: String, state: true },
+    notice: { type: String, state: true },
+  };
+
+  constructor(){
+    super();
+    this.data = null;
+    /*
+      Only what was touched, shaped like the request body. An untouched field is not sent at all,
+      which is what makes "blank means unchanged" true on the wire and not only in the route.
+    */
+    this.edits = { global: {}, providers: {} };
+    this.saving = false;
+    this.error = '';
+    this.notice = '';
+  }
+
+  /*
+    Lifecycle
+  */
+
+  connectedCallback(){
+    super.connectedCallback();
+    this.load();
+  }
+
+  /*
+    Data
+  */
+
+  load = async () => {
+    const [error, data] = await getSettings();
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.data = data;
+    this.edits = { global: {}, providers: {} };
+  };
+
+  editGlobal = (name, value) => {
+    this.edits = { ...this.edits, global: { ...this.edits.global, [name]: value } };
+  };
+
+  editProvider = (provider, name, value) => {
+    const current = this.edits.providers[provider] || {};
+    this.edits = { ...this.edits, providers: { ...this.edits.providers, [provider]: { ...current, [name]: value } } };
+  };
+
+  save = async () => {
+    this.saving = true;
+    this.error = '';
+    this.notice = '';
+
+    const [error] = await saveSettings(this.edits);
+    this.saving = false;
+
+    if(error){
+      this.error = error.msg;
+      return;
+    }
+
+    this.notice = 'Saved.';
+    await this.load();
+  };
+
+  clearSecret = async name => {
+    this.edits = { ...this.edits, providers: { ...this.edits.providers, [name]: { client_secret: null } } };
+    await this.save();
+  };
+
+  copy = (text) => {
+    navigator.clipboard?.writeText(text);
+    this.notice = 'Copied.';
+  };
+
+  get dirty(){
+    return Object.keys(this.edits.global).length > 0 || Object.keys(this.edits.providers).length > 0;
+  }
+
+  /*
+    Rendering
+  */
+
+  #valueOf = (provider, name, stored) => this.edits.providers[provider.name]?.[name] ?? stored;
+
+  #renderStatus(provider){
+    if(provider.active) return html`<span class="tc-success">Active — shown on the login and register pages</span>`;
+    if(provider.enabled && !provider.configured) return html`<span class="tc-warning">Incomplete — needs both a client id and a client secret before it is shown</span>`;
+    return html`<span class="tc-muted">Off</span>`;
+  }
+
+  #renderProvider(provider){
+    const secretEdit = this.edits.providers[provider.name]?.client_secret;
+
+    return html`
+      <div class="card mb">
+        <h3>
+          ${provider.mono
+            ? html`<k-icon class="mrh" src="/oauth/icons/${provider.icon}"></k-icon>`
+            : html`<img class="icon mrh" src="/oauth/icons/${provider.icon}" alt="" />`}${provider.label}
+        </h3>
+        <p class="small">${this.#renderStatus(provider)}</p>
+
+        <label class="checkbox">
+          <input
+            type="checkbox"
+            .checked=${this.#valueOf(provider, 'enabled', provider.enabled)}
+            @change=${event => this.editProvider(provider.name, 'enabled', event.target.checked)}
+          />
+          Offer “Continue with ${provider.label}”
+        </label>
+
+        <p class="small tc-muted mt">
+          Create an OAuth app in the <a href=${provider.consoleUrl} target="_blank" rel="noopener">${provider.label} developer console</a>
+          and give it this redirect URI:
+        </p>
+        <div class="d-f mbh">
+          <input class="ff-mono flex" type="text" readonly .value=${provider.redirectUri} />
+          <button class="secondary" @click=${() => this.copy(provider.redirectUri)}><k-icon name="content_copy"></k-icon> Copy</button>
+        </div>
+
+        <label>
+          <span class="d-b">Client id</span>
+          <input
+            type="text"
+            autocomplete="off"
+            .value=${this.#valueOf(provider, 'client_id', provider.clientId)}
+            @input=${event => this.editProvider(provider.name, 'client_id', event.target.value)}
+          />
+        </label>
+
+        <label>
+          <span class="d-b">Client secret ${provider.hasSecret ? html`<span class="small tc-success">· set</span>` : ''}</span>
+          <input
+            type="password"
+            autocomplete="off"
+            placeholder=${provider.hasSecret ? '•••••••• — leave blank to keep' : ''}
+            .value=${typeof secretEdit === 'string' ? secretEdit : ''}
+            @input=${event => this.editProvider(provider.name, 'client_secret', event.target.value)}
+          />
+          ${provider.hasSecret ? html`
+            <button class="link small" ?disabled=${this.saving} @click=${() => this.clearSecret(provider.name)}>Clear this secret</button>
+          ` : ''}
+        </label>
+
+        ${provider.extraFields.map(field => html`
+          <label>
+            <span class="d-b">${field.label}</span>
+            <span class="small tc-muted d-b">${field.help}</span>
+            <input
+              type="text"
+              autocomplete="off"
+              .value=${this.#valueOf(provider, field.name, field.value)}
+              @input=${event => this.editProvider(provider.name, field.name, event.target.value)}
+            />
+          </label>
+        `)}
+      </div>
+    `;
+  }
+
+  #renderGlobal(){
+    const { global } = this.data;
+    const value = (name, key) => this.edits.global[name] ?? global[key];
+
+    return html`
+      <h2>Site</h2>
+
+      <label>
+        <span class="d-b">Site address</span>
+        <span class="small tc-muted d-b">
+          Where this site is reached, such as https://example.com. Leave empty to work it out from each request —
+          fine for a site reached directly, wrong behind a proxy that changes the scheme or the host.
+          Every redirect URI below is built from it.
+        </span>
+        <input type="text" placeholder="https://example.com" .value=${value('base_url', 'baseUrl')} @input=${event => this.editGlobal('base_url', event.target.value)} />
+      </label>
+
+      <label>
+        <span class="d-b">After signing in</span>
+        <span class="small tc-muted d-b">The page a visitor lands on, unless the page they came from asked for somewhere else.</span>
+        <input type="text" .value=${value('after_login_path', 'afterLoginPath')} @input=${event => this.editGlobal('after_login_path', event.target.value)} />
+      </label>
+
+      <label class="checkbox">
+        <input
+          type="checkbox"
+          .checked=${value('link_verified_emails', 'linkVerifiedEmails')}
+          @change=${event => this.editGlobal('link_verified_emails', event.target.checked)}
+        />
+        Connect a provider sign-in to an existing account with the same email, when the provider has confirmed that email
+      </label>
+      <p class="small tc-muted">
+        Turned off, someone who signed up with a password and later uses Google with the same address gets a second account.
+        A provider that does not confirm emails (Facebook, Microsoft) is never connected to an existing account either way.
+      </p>
+    `;
+  }
+
+  render(){
+    if(!this.data) return this.error ? html`<p class="tc-danger">${this.error}</p>` : html`<k-spinner></k-spinner>`;
+
+    return html`
+      ${!this.data.encryptionConfigured ? html`
+        <div class="card tc-danger mb">
+          <strong>SETTINGS_ENCRYPTION_KEY is not set on this server.</strong>
+          <p class="small">
+            Client secrets are encrypted with it, so none can be stored until it exists. Generate one with
+            <code class="ff-mono">node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"</code>,
+            put it in the site’s environment, and restart. Back it up — losing it makes every stored secret unrecoverable.
+          </p>
+        </div>
+      ` : ''}
+      ${this.error ? html`<p class="tc-danger">${this.error}</p>` : ''}
+      ${this.notice ? html`<p class="tc-success small">${this.notice}</p>` : ''}
+
+      <h2>Providers</h2>
+      ${this.data.providers.map(provider => this.#renderProvider(provider))}
+
+      ${this.#renderGlobal()}
+
+      <button class="primary mt" ?disabled=${this.saving || !this.dirty} @click=${this.save}>
+        ${this.saving ? 'Saving…' : 'Save settings'}
+      </button>
+    `;
+  }
+}
+
+customElements.define('k-oauth-settings', ProviderSettings);

package/admin/index.page.html

@@ -0,0 +1,66 @@
+<!--
+locked: true
+-->
+<page title="Sign-in Providers - Admin">
+<content>
+  <script type="module" src="/kempo/components/PermissionTarget.js"></script>
+  <script type="module" src="/kempo-ui/components/Tabs.js"></script>
+  <script type="module" src="/admin/extension/kempo-oauth/components/ProviderSettings.js"></script>
+  <script type="module" src="/admin/extension/kempo-oauth/components/LinkedAccounts.js"></script>
+
+  <div>
+    <h1>Sign-in Providers</h1>
+    <p class="tc-muted">
+      Let visitors sign in or register with an account they already have. Each provider needs an OAuth
+      app created in its own developer console; paste that app’s client id and secret here. Nothing
+      appears on the login and register pages until a provider is switched on and has both.
+    </p>
+
+    <k-tabs id="tabs" active="providers" persistent-id="kempo-oauth-admin-tab">
+      <k-tab id="providersTab" for="providers">Providers</k-tab>
+      <k-tab id="accountsTab" for="accounts">Connected accounts</k-tab>
+
+      <k-tab-content id="providersContent" name="providers">
+        <k-oauth-settings></k-oauth-settings>
+      </k-tab-content>
+
+      <k-tab-content id="accountsContent" name="accounts">
+        <k-oauth-accounts></k-oauth-accounts>
+      </k-tab-content>
+    </k-tabs>
+
+    <!--
+      k-tabs finds its tabs with a direct-child query, so nothing can wrap a <k-tab>/<k-tab-content>
+      pair — not even a hidden element. k-permission-target reaches in by id and hides the tab and
+      its pane in place instead. A courtesy only: the actual boundary is server-side, on each route.
+    -->
+    <k-permission-target has="oauth:settings" target="#providersTab, #providersContent"></k-permission-target>
+    <k-permission-target has="oauth:view" target="#accountsTab, #accountsContent"></k-permission-target>
+  </div>
+
+  <script type="module">
+    import { getAllCurrentUserPermissions } from '/kempo/sdk.js';
+
+    await customElements.whenDefined('k-tabs');
+
+    /*
+      persistent-id can restore whichever tab a returning visitor left open, including one this
+      visitor cannot see if their permissions changed since. The targets above hide a tab and its
+      pane; this makes sure a hidden one is never left selected.
+    */
+    const [error, data] = await getAllCurrentUserPermissions();
+    const permissions = new Set(error ? [] : (data?.permissions || []));
+
+    const tabs = document.getElementById('tabs');
+    if(tabs){
+      const visibility = {
+        providers: permissions.has('oauth:settings'),
+        accounts: permissions.has('oauth:view'),
+      };
+      if(!visibility[tabs.active]){
+        const fallback = Object.keys(visibility).find(name => visibility[name]);
+        if(fallback) tabs.active = fallback;
+      }
+    }
+  </script>
+</content>

package/admin/nav.global.html

@@ -0,0 +1,3 @@
+<content id="kempo-oauth-nav" name="Sign-in Providers" owner="kempo-oauth" enabled="true" locked="true" location="admin-nav-extensions" priority="4">
+<k-aside-item icon="login" href="/admin/extension/kempo-oauth/" no-expand>Sign-in Providers</k-aside-item>
+</content>

package/install.js

@@ -0,0 +1,48 @@
+import { sql } from 'drizzle-orm';
+import db from 'kempo/server/db/index.js';
+
+/*
+  Two things the declarative config cannot do.
+
+  **The indexes.** kempo's installer generates `CREATE TABLE` from the Drizzle schema and reads
+  columns and primary keys off it — indexes and unique constraints declared on a table are not
+  carried across. Here one of them is a correctness guarantee: without a unique index on
+  `(provider, providerUserId)` two rows can claim the same Google account, and a sign-in then lands
+  on whichever user the database happens to return first. So it is created here, by hand, matching
+  what server/db/schema.js declares.
+
+  **The warning.** Every client secret this extension stores is a `secret` setting, and kempo can
+  only encrypt those when SETTINGS_ENCRYPTION_KEY is set. Without it the settings screen refuses to
+  save a secret, and the first sign of trouble is a form that fails with no obvious cause. Saying so
+  at install time is the difference between a two-minute fix and an hour.
+*/
+
+const INDEXES = [
+  sql`CREATE UNIQUE INDEX IF NOT EXISTS "kempoOauthAccount_provider_idx" ON "kempoOauthAccount" ("provider", "providerUserId")`,
+  sql`CREATE INDEX IF NOT EXISTS "kempoOauthAccount_user_idx" ON "kempoOauthAccount" ("userId")`,
+];
+
+export default async () => {
+  for(const statement of INDEXES){
+    try {
+      await db.execute(statement);
+    } catch(error) {
+      console.warn(`[kempo-oauth] Could not create an index: ${error.message}`);
+    }
+  }
+
+  if(!process.env.SETTINGS_ENCRYPTION_KEY){
+    console.warn([
+      '[kempo-oauth] SETTINGS_ENCRYPTION_KEY is not set, so client secrets cannot be stored.',
+      '  Generate one with: node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"',
+      '  Put it in .env and restart. Back it up somewhere — losing it makes every stored secret on the site unrecoverable.',
+    ].join('\n'));
+    return;
+  }
+
+  console.log([
+    '[kempo-oauth] Installed. Add a provider at /admin/extension/kempo-oauth/.',
+    '  The buttons appear under the login and register forms. If your site\'s own login and register pages',
+    '  predate the "login-form-after" / "register-form-after" slots, add them — see the README.',
+  ].join('\n'));
+};