@jimhoyd/urlcode-auth 0.1.0-alpha.1

package/IMPLEMENTATION-STATUS.md

@@ -0,0 +1,37 @@
+# Auth implementation status
+
+Status: `@jimhoyd/urlcode-auth` 0.1.0-alpha.1 is the first npm release (core issue #78); it requires the published `@jimhoyd/urlcode` 0.4.x and `@jimhoyd/urlcode-ui` 0.1.x alphas. The implemented auth and shared-presentation work is merged to main. The source plan is URLCode PR #54; cross-repository release acceptance is tracked in https://github.com/jimhoyd-com/urlcode/issues/58. The generic core extension contract from PR #59 is merged. Implementation and synthetic acceptance do not establish production readiness.
+
+Implemented and covered by automated tests: durable SQLite accounts; bounded scrypt and hash migration; email/password and numeric email codes; OIDC with explicit linking; Google/Apple adapters; WebAuthn registration, login and step-up; TOTP/recovery; opaque sessions and revocation; role ceilings; registration modes; terms and scoped metadata; email change cooldown/cancellation; deletion grace; exports; key rotation; backup/restore; operator CLI/scaffolding; SES/development senders; safe themes and locale catalogue; admin service operations including dual-approval cases and bounded impersonation. Device recognition supports notices; separate opt-in, revocable remembered-device authority can exempt ordinary MFA without granting fresh step-up. Explicit passkey second-factor enrollment requires an independent credential. Optional breach checking is an operator-selected external service.
+
+Resumable verification-first password/passkey signup (including waitlist approval) and opt-in email-mediated factor recovery with a 24-hour cancellation window and recovery-session-only reenrollment are implemented.
+
+Mandatory verification/TOTP enrollment, operator standard/hardened presets and explicit pinned configuration migration are implemented; hardened requires email and breach-screening adapters.
+
+Kit adoption (urlcode-auth issue #9, core plan §7.2) is implemented: every account screen is an `auth/*` kit template with a declared view model and sample view (`authTemplates`, `authUiTemplates`, `authCatalogue`); `authExtension({ ui })` renders through `ui.kit.page` when the host supplies the `ui` extension and through the shared primitives otherwise. The HTTP suites run under both render paths; a doctor-style suite renders every template with its sample and with the view a real request computes, checks escaping of user-controlled values on kit pages and the nonce-bound CSP. A themed browser walkthrough of the account pages remains a manual acceptance step.
+
+## Additional implemented acceptance
+
+- Bounded localized email copy, durable progressive password backoff, trusted-client and signup-domain velocity budgets, optional fixed-origin Turnstile verification/widget, and pinned disposable-domain data.
+- Integrated maker/checker manual recovery, staged administrative account actions and audited identifier reveal/notes. Manual recovery is an operator process; public lost-everything intake and recovery contacts remain later scope.
+- Offline `auth-baseline` runs 17 synthetic checks on a passing run (extra failure-only markers are recorded when a probe, deadline or cleanup fails); anonymous `verify-deployment` inspects headers/cookies without claiming provider readiness.
+- Local browser walkthrough exercised identifier-first password login, account page, admin dashboard, filtered directory and masked detail. It found and corrected the no-referrer/Origin form failure. This is not a complete WCAG 2.2 AA assessment.
+
+- The source-only [synthetic recovery drill](RECOVERY-DRILL.md) exercises online backup, isolated reopen, configuration/key refusal and explicit session revocation after snapshot restore. Its 18 checks do not establish production disaster recovery or RTO/RPO.
+
+## Remaining first-release acceptance
+
+- Complete accessibility assessment, browser/device WebAuthn coverage, deployment/soak/backup-recovery exercises and independent security review.
+- Operator wiring of sender monitoring and lifecycle delivery policy. Hooks and security notices are best-effort after commit, without a durable retry queue (signed webhooks/retries are later scope).
+- Refresh the recorded package and CI evidence whenever code or dependency pins change; the merged implementation baseline is recorded in ACCEPTANCE.md.
+
+Live Google/Apple/SES testing is explicitly deferred by the project owner and is not a blocker for local implementation. It remains unverified. Synthetic signed protocol tests do not establish vendor configuration or delivery readiness.
+
+## Agreed architecture corrections
+
+Auth/admin live in independent repositories. The core owns generic revision-pinned extension contracts and never depends on auth. SQLite and privileged transactions belong to the trusted operator service. Project YAML cannot select host modules or credentials. Safe package renderers replace arbitrary project templates. The initial auth target is Node with operator-owned durable storage; runtime adapter availability does not make this SQLite service portable to every deployment target.
+
+## Recorded acceptance
+
+See [ACCEPTANCE.md](https://github.com/jimhoyd-com/urlcode-auth/blob/main/ACCEPTANCE.md) for exact merged revisions, automated coverage,
+clean-install evidence and the remaining operational validation boundary.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Jimmy Ho
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,261 @@
+# URLCode auth
+
+An optional, operator-installed authentication extension for URLCode. This repository contains the Node/SQLite implementation: password and passkey authentication, OpenID Connect, email codes, TOTP, recovery codes, versioned registration profiles, account lifecycle operations, administrative service operations and trusted HTML pages.
+
+[![Verify](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml)
+
+The implementation is under active review. Local tests and builds are evidence of those checks, not an independent security assessment, production deployment, provider certification or recovery/soak result. See [SECURITY.md](SECURITY.md) for the trust boundary and [the first-release coverage review](docs/SPIKE-AUTH.md) for the proposal; the proposal is not a list of completed features.
+
+## Install
+
+`@jimhoyd/urlcode-auth` is published to npm as an alpha alongside its peers. Install the three packages together; the peer ranges in `package.json` require `@jimhoyd/urlcode` 0.4.0-alpha.1 or a later 0.4.x and `@jimhoyd/urlcode-ui` 0.1.0-alpha.1 or a later 0.1.x, and the release workflow builds and tests against exactly those registry versions.
+
+```sh
+npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth
+npx urlcode init my-site --with auth
+```
+
+`urlcode init --with auth` is core's layered scaffold; `npx urlcode-auth init --directory /absolute/new-account-site` scaffolds an auth-only project. Either writes `app/urlcode.yaml`, external `host.mjs` and `operator-service.mjs`, a private `data/` directory and independent encryption/CSRF keys, and refuses an existing destination. Its README gives the exact next steps.
+
+Alpha caveat: the source is complete for the first release and its automated checks pass, but independent security review, accessibility assessment, browser/device WebAuthn coverage and deployment/soak/recovery exercises are still pending (see [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md)). Alpha versions may change public exports, configuration keys and the SQLite schema between releases without a migration path. Do not run an alpha on production accounts.
+
+Use a current supported Node release with a patched SQLite build. The actual runtime requirement is a Node build whose bundled SQLite (`process.versions.sqlite`) is 3.51.3 or newer, or a patched 3.50.7+ / 3.44.6+ branch release; `engines.node` alone does not encode this, and the service (`src/auth-store.ts`) refuses other builds with `patched_sqlite_required` even when the package's minimum Node version is satisfied.
+
+Every release tarball is attested from the tagged commit: `gh attestation verify jimhoyd-urlcode-auth-<version>.tgz --repo jimhoyd-com/urlcode-auth`. `npm view @jimhoyd/urlcode-auth` shows the published provenance.
+
+## Install from reviewed source
+
+Operators who pin exact reviewed commits rather than registry versions can build the same packages locally. A registry version alone does not establish that a revision was reviewed: this implementation requires the core extension contract introduced by [core PR #59](https://github.com/jimhoyd-com/urlcode/pull/59). Use its reviewed implementation or a reviewed successor containing it, pinned to an exact commit. Do not infer approval from the current branch name.
+
+This package also depends on the shared `@jimhoyd/urlcode-ui` peer, which owns document layout, semantic fields, escaping, themes and the locale engine; authentication/administration behavior remains here. Core can use UI without auth/admin. Source CI (`verify.yml`) checks the peers out at the commits in [`peers.json`](peers.json) and needs the narrow `URLCODE_UI_READ_TOKEN`; the release workflow resolves them from the registry instead.
+
+Each repository has a lockfile. The source packaging helper installs dependencies with lifecycle scripts disabled, builds the reviewed packages (core, then UI, then their consumers), installs local peer tarballs in dependency order and writes package integrity/revision metadata. It does not publish. All source trees must be committed and clean. `--core`, `--auth`, `--ui`, `--core-revision` and `--out` are required. Replace these illustrative paths with your reviewed locations. `--core-revision` defaults to the `urlcode` entry in [`peers.json`](peers.json), the single source of verified peer revisions; pass it explicitly only to override:
+
+```sh
+node scripts/pack-sources.mjs \
+  --core /absolute/source/urlcode \
+  --ui /absolute/source/urlcode-ui \
+  --auth /absolute/source/urlcode-auth \
+  --admin /absolute/source/urlcode-admin \
+  --core-revision REVIEWED_40_CHARACTER_COMMIT_SHA \
+  --out /absolute/new-private-package-directory
+```
+
+Omit `--admin` for auth only. `--offline` forbids network package resolution and requires a populated dependency cache. `--skip-install` reuses installed third-party dependencies; local peer tarballs are still installed. The script does not alter dependency manifests or lockfiles. Run `npm run verify` in each repository separately; source packaging runs typecheck/build, not the HTTP suite.
+
+Install all required local tarballs together (core, UI and auth; admin if built) in an operator-owned directory with a private `package.json`. For example, after checking the manifest:
+
+```sh
+npm install /absolute/packages/jimhoyd-urlcode-0.4.0-alpha.1.tgz /absolute/packages/jimhoyd-urlcode-ui-0.1.0-alpha.1.tgz /absolute/packages/jimhoyd-urlcode-auth-0.1.0-alpha.1.tgz
+npx urlcode-auth init --directory /absolute/new-account-site
+```
+
+Tarball names and versions must match the generated manifest. Install the same reviewed local tarballs inside the generated directory so its host modules resolve them.
+
+## Programmatic scaffold
+
+`scaffold({directory, project, hostFile, names})` returns the auth pieces of a layered project (YAML fragments, host imports and entries, private files with in-memory key material, a README section and next steps) without writing anything; `initAuthentication` is assembled from it. Core's `urlcode init --with auth` calls this export and merges it with other extensions.
+Exported types: `ScaffoldRequest`, `ScaffoldResult`, `ScaffoldFile`.
+
+## Operator activation
+
+Route YAML declares a versioned logical extension, not executable code:
+
+```yaml
+version: '1'
+extensions:
+  auth:
+    version: '1'
+    config:
+      registration: 'off'
+routes:
+  /account/*:
+    extension: auth
+    methods: [GET, HEAD, POST]
+  /private:
+    respond: {text: Signed in}
+    policies:
+      extensions:
+        auth: {}
+```
+
+The external host creates an AuthService and supplies `authExtension({service, csrfKey, projectSha256})`. The generated host requires a canonical HTTPS `AUTH_ORIGIN` and a static `PROJECT_SHA256` copied after review. Inspecting a revision with `inspectExtensionRevision(project)` grants nothing; never compute and automatically approve the current project during activation. The runtime receives the same origin through `--origin` and loads the absolute external host with `--host-file`. Guest/application code never chooses the module, database path, keys, sender credentials or grants.
+
+Registration starts off. Bootstrap the first administrator through `urlcode-auth bootstrap --operator-file /absolute/operator-service.mjs`, supplying `{email,password}` as bounded JSON on stdin. Never place passwords in command arguments or source files. The command returns account metadata, not the session token. A role/default-role configuration change is a reviewed operator change, not an administration-page edit.
+
+## Authentication and presentation
+
+`createAuthService` owns a private SQLite database outside the application directory. Its operations enforce authority, fresh authentication, delegation ceilings, replay protection and transaction boundaries. Callers must preserve the distinction between unrestricted operator APIs and actor-token administrative APIs. `authExtension` adds HTTP cookies, same-origin CSRF checks, bounded bodies and trusted pages.
+
+Optional factories supply Google/Apple/generic OIDC and passkey providers. Unconfigured providers are not offered. Synthetic cryptographic fixtures do not prove real Google, Apple, authenticator or SES deployment behavior. The auth extension currently declares **Node only**; generic core extension support for AWS/Vercel does not make this SQLite service portable to their deployment environments.
+
+`createPresentation` supplies configured locale catalogues, plural rules, RTL, and validated theme variables/local logo paths. Messages are plain text and escaped by renderers. It does not load executable project templates or arbitrary HTML/CSS. Translation coverage and accessibility require review; the helper does not establish WCAG conformance. Registration metadata is descriptive data and never authorization authority. Private metadata is excluded from public projections; public and unsafe fields remain untrusted.
+
+## Optional breached-password screening
+
+An operator can configure `checkPassword: createPasswordBreachChecker()` on `createAuthService`. This optional Have I Been Pwned range check sends only the SHA-1 prefix, requests padded responses, bounds concurrency/deadline/response bytes, and fails closed when the check cannot complete. It does not send the password or full hash to the service. Configuring the callback introduces an external service dependency; do not enable it silently or describe it as a complete hardened preset. Offline fixtures are not evidence of live service availability.
+
+## Email and local development
+
+`createSesSender({region, from, origin, authMount, credentials?})` returns a callable token sender with `sendEmailCode`, `notify` and `close`. Wire callbacks explicitly into the auth/admin factories. Production credentials come from operator configuration or the SDK credential chain; never put them in YAML. Delivery is bounded and cancellable; services cannot guarantee that an email reaches an inbox.
+
+`createDevelopmentSender` requires `allowDevelopment: true` and either a private output directory outside the project plus its `projectRoot`, or `allowConsoleTokens: true`. File notices use exclusive `0600` files and a bounded count. Console mode deliberately exposes development tokens and must never feed shared production logs. Sender helpers do not infer safety from `NODE_ENV`.
+
+## Operations and recovery
+
+Run `urlcode-auth --help` for the current CLI. Operator commands have full database authority; stdin avoids putting secrets in process arguments. User/audit listings currently return a bounded page; use service pagination for complete exports. Doctor's successful local database check is not live-provider verification.
+
+| Command | Arguments | Purpose |
+| --- | --- | --- |
+| `init` | `--directory NEW_DIRECTORY` | Scaffold a new account site; refuses an existing destination |
+| `bootstrap` | `--operator-file`, JSON `{email,password}` on stdin | Create the first administrator; returns account metadata, not a session token |
+| `users` | `--operator-file` | List accounts (bounded page of 100) |
+| `sessions` | `--operator-file`, JSON `{accountId}` on stdin | List an account's sessions |
+| `revoke` | `--operator-file`, JSON `{accountId}` on stdin | Revoke all sessions of an account |
+| `audit` | `--operator-file` | List audit events (bounded page of 100) |
+| `import` | `--operator-file`, JSON `{users:[{email,passwordHash,emailVerified?}]}` on stdin | Import generic password hashes; only those fields are accepted |
+| `rotate-key` | `--operator-file` | Re-encrypt records with the active encryption key; reports changed/remaining |
+| `purge` | `--operator-file` | Permanently remove accounts whose deletion grace has elapsed |
+| `cleanup` | `--operator-file` | Sweep expired sessions/tokens (bounded batch) |
+| `configuration` | `--operator-file` | Print configuration revision, registration mode, security policy and roles |
+| `doctor` | `--operator-file` | Local database/configuration readiness check |
+| `validate` | `--operator-file` | Offline validation of the loaded service's configuration |
+| `auth-baseline` | none (refuses `--operator-file`) | Offline synthetic checks against a temporary runtime |
+| `verify-deployment` | JSON `{origin,authMount,allowDevelopment?,allowTurnstile?}` on stdin | Anonymous header/cookie checks of a deployed site |
+| `backup` | JSON `{database,destination,projectRoot}` on stdin | Online SQLite backup to a new private path |
+| `restore` | JSON `{backup,destination,projectRoot}` on stdin | Restore a backup to a new private path |
+
+`--operator-file` is an absolute path to a module that default-exports an `AuthService`.
+
+Backup/restore accepts JSON paths on stdin. `createBackup({database,destination,projectRoot})` uses SQLite's online backup API, including committed WAL pages, with a bounded worker and integrity checks. `restoreBackup({backup,destination,projectRoot})` restores to a **new** path. Both require private operator paths outside the project and refuse overwrite. Never copy only a live `.sqlite` file and assume its WAL is included.
+
+Back up encryption keys, CSRF keys and reviewed static configuration separately. Database snapshots contain sensitive account/audit data and password hashes, but do not export key files. Restoring historical data also restores historical sessions/tokens and revocation state: plan revocation and recovery before reopening traffic. Rotate keys by adding a new active key, retaining decryption keys while bounded migration reports remaining records, then remove old keys only after completion and backup verification. Old writers fail closed after activation switches. Keep a tested isolated restore procedure.
+
+The host owns the shared service and sender lifecycle. Close them once after all extension runtimes stop. Scheduled purge/sweep operation and backups are operator responsibilities; opportunistic cleanup is not a retention policy.
+
+Apache-2.0. `release.yml` publishes a tagged commit that is on `main` to npm through trusted publishing when the repository variable `PUBLISH_NPM` is `true`; `verify.yml` publishes nothing.
+
+## Operator presets and enrollment
+
+`createAuthPreset({preset: 'standard', origin, rpName, sender?})` supplies passkeys, standard session limits and seven-day deletion grace. Without a sender it returns an explicit notice that email flows are unavailable. TOTP and recovery are service capabilities; remembered devices can optionally exempt ordinary MFA, but never grant fresh step-up authority.
+
+`createAuthPreset({preset: 'hardened', origin, rpName, sender, checkPassword: createPasswordBreachChecker()})` requires both adapters and supplies mandatory email verification followed by TOTP enrollment, shorter sessions and 30-day deletion grace. Spread `preset.service` into `createAuthService` and `preset.extension` into `authExtension`, together with your operator paths, keys and static project pin. Choosing the online breach checker makes password creation/reset depend on that external service; inject an approved local checker if needed. Deliberate overrides change the effective policy and should be reviewed.
+
+Restricted enrollment sessions can verify their email and enroll TOTP, but cannot authorize protected application routes or administration. Required verification revokes old sessions and requires a fresh sign-in before factor enrollment. Public routes without auth policies remain public. These controls do not establish independent security certification or live provider readiness.
+
+Configuration is database-pinned. Before changing modes, roles or security requirements, run `urlcode-auth configuration --operator-file /absolute/operator-service.mjs` and retain its revision. Review the new operator configuration and pass `approveConfigurationChangeFrom: 'the-old-64-character-revision'` on the first `createAuthService` startup. The generated operator file accepts that explicit approval through `AUTH_CONFIG_FROM`. A matching already-applied migration can be repeated safely; an unrelated pin fails.
+
+Migration preserves accounts, enrolled credentials and history, while revoking sessions and pending authentication/registration state, closing pending cases and recording an audit entry. Existing roles must remain valid and active administration cannot be removed accidentally. Valid pending-deletion cancellation links retain only their original expiry. Old workers reject reads and writes after migration; restart every instance with the reviewed configuration, remove the approval variable, and separately review/pin the changed route project. Schedule the transition as a maintenance operation; do not edit database metadata manually.
+
+`englishCatalogue` (also exported as `authCatalogue`) exports the semantic UI keys for catalogue authors. Translations are plain text and escaped at rendering; runtime templates never execute project markup. No complete non-English language pack is bundled. Dates, provider identifiers and user data retain their own values.
+
+## Presentation
+
+Every account screen is an `auth/*` template in the urlcode-ui kit language with a declared view model (`authTemplates`, each with a sample view; `authUiTemplates` is the block the `ui` extension takes). The extension computes the view and the template only places it: a template cannot change which steps a flow has, what a form validates, what is escaped, or the CSRF field and headers a page sends. Forms, fields and buttons arrive in the view as renderer-produced markup built by the shared primitives.
+
+`authExtension` takes an optional `ui`, the object `createUiExtension` returns. Declare `ui` first in the host file so the runtime activates it before auth; auth reads `ui.kit` per request and never captures it at activation.
+
+```js
+import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
+import { authExtension, authCatalogue, authUiTemplates } from '@jimhoyd/urlcode-auth';
+const ui = createUiExtension({ projectSha256, projectRoot: '/absolute/site', sources: [authCatalogue], extensions: [authUiTemplates] });
+export default { extensions: [ui.registration, authExtension({ service, csrfKey, projectSha256, ui })] };
+```
+
+```yaml
+extensions:
+  ui: { version: "1", config: { theme: { name: Acme }, templates: ui/templates } }
+routes:
+  /assets/ui/*: { extension: ui, methods: [GET, HEAD] }
+```
+
+With `ui`, screens render through `ui.kit.page`: the project's theme, layout, hashed stylesheet and copy apply, a project file `ui/templates/auth/<screen>.html` shadows the shipped template, and `urlcode-ui doctor` reports every `auth/*` template behind its view model. Copy then resolves through the kit's presentation, which carries the kit catalogue, the auth catalogue and the project's `extensions.ui` copy; omit `presentation` in that case. If both are given, `presentation` wins and must register the kit catalogue for the layout's own keys.
+
+Without `ui`, nothing changes: screens render the same templates through the shared primitives with `presentation` (or the bundled English catalogue). The `presentation` option remains the fallback; core plans to retire it one minor version after the kit path ships. The auth passkey script and the optional challenge widget are nonce-bound on both paths and the page CSP admits only that nonce (plus the challenge origin when configured).
+
+Changing `configurationTag` deliberately advances the approved configuration revision for provider/callback/profile-policy deployments that cannot be fingerprinted as simple data. The service does not automatically fingerprint executable callbacks. Session idle and absolute limits do participate in the declared configuration fingerprint.
+
+### Verification-first signup
+
+The browser registration entry point resumes a short-lived, browser-bound signup
+wizard. With `requireEmailVerification`, it verifies an emailed numeric code before
+accepting a password or passkey; `sendSignupCode` must be configured. Credentials,
+profile and required consent are finalized together. Open/invited signup creates
+one account/session transaction; waitlist signup creates only a pending application
+until an administrator approves it. Passkey applications retain their credential
+and account binding through approval. Existing accounts are never overwritten:
+the identifier step gives the same next page and sends a registration-attempt
+notice privately. The low-level operator registration/bootstrap methods remain
+explicit privileged provisioning APIs, not public HTTP signup shortcuts.
+
+### Lost second-factor recovery
+
+`allowEmailFactorRecovery: true` explicitly enables an email fallback for verified
+accounts that lost their second factor. It is disabled by default because control
+of the mailbox becomes a recovery authority. Configure `sendFactorRecovery`; the
+bundled SES/development senders and presets provide it. The flow confirms a private
+email link in the originating browser, starts a 24-hour waiting period and provides
+a separate cancellation link. GET requests never consume either capability.
+
+Completion checks the account version, revokes sessions and pending authority,
+removes the old TOTP/recovery codes, and issues an enrollment-only session. Only that
+recovery session can enroll the replacement factor; ordinary password/provider
+logins cannot race it, even when the site's global MFA requirement is off. No
+application authority returns until the replacement factor is confirmed. Recovery
+state expires, is rate-limited, survives restart and is revoked by configuration
+migration. This is email-based factor recovery, not proof of a person's legal
+identity or the later public lost-everything workflow.
+
+### Anonymous deployment checks
+
+Run `urlcode-auth verify-deployment` with bounded JSON on stdin containing the
+canonical HTTPS `origin` and `authMount`. It performs two anonymous GET requests,
+checks the expected login/unauthenticated account status, restrictive CSP,
+no-store, path-private referrer and nosniff headers, and secure host-only cookies. It does not send
+credentials, follow redirects, read response bodies, send email or create accounts.
+A failed check exits nonzero and prints only named booleans, never response bodies
+or network errors. `allowDevelopment: true` permits HTTP only for loopback hosts.
+These checks cover the observed public responses; they do not establish live
+provider readiness, security assessment, recovery or load-test results.
+
+### Passkey second factors and remembered devices
+
+Set `allowPasskeySecondFactor: true` to let a user explicitly enroll an owned,
+user-verified passkey as a second factor at `/account/second-factors`. A passkey
+used for primary sign-in cannot also satisfy the second factor in that sign-in.
+WebAuthn challenges bind to the browser; opaque factor proofs are consumed with
+the primary credential, account version and counter in the final transaction.
+TOTP/recovery-code alternatives remain available. Restricted enrollment may add a
+factor through a narrowly scoped path, including the recovery-session grant.
+
+Set `trustedDeviceTtlMs` (at most 30 days; default disabled) to offer
+`/account/trusted-devices`. Remembering a device requires recent actual MFA and an
+explicit user action. It creates a separate Secure, HttpOnly, host-only cookie;
+ordinary device recognition is never an MFA exemption. Remembered sign-in has no
+fresh authentication timestamp and cannot satisfy admin/credential step-up or mint
+another exemption. Users can revoke individual remembered devices; account
+security/version changes invalidate them. These options are part of the pinned
+operator configuration and require the explicit migration workflow when changed.
+
+`blockDisposableEmails: true` optionally refuses new registrations using the
+bundled disposable-domain snapshot, including subdomains. The dataset revision is
+part of the configuration fingerprint. Existing-account login/recovery is not
+blocked by this policy. Exact operator allow/block lists still apply. The snapshot
+is fallible and may reject legitimate addresses; see
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for provenance and CC0 data terms.
+
+### Offline operational checks
+
+`urlcode-auth validate --operator-file /absolute/operator/auth.mjs` checks the loaded service's configuration revision, registration mode, bounded role definitions and public security policy. Output contains policy values and aggregate counts, not accounts, credentials, database paths or callback configuration. It requests no migration or account mutation. Loading an operator module executes trusted initialization: use an existing configuration without migration approval, and review that module's own startup behavior. This command does not sandbox operator code or verify providers.
+
+`urlcode-auth auth-baseline` requires no operator module and refuses one. It creates private temporary fixtures and an auth database outside the fixture project, runs a bounded child process, then removes them. Seventeen named checks (listed in `test/auth-baseline.test.ts`) exercise the real local runtime without opening a listener: anonymous authorization denial, CSRF and origin enforcement, Secure/HttpOnly/Strict host cookies, no-store auth responses, credential withholding from guest Request and derived header context, revocation, and restricted enrollment authority. Extra failure-only markers are recorded when a probe, deadline or cleanup fails. A failed check or deadline produces a nonzero exit status and redacted results. The command uses no customer state, network, mail or live providers. These synthetic checks are limited regression evidence, not an independent security assessment, deployment certification, browser test, load test or recovery drill.
+
+`verify-deployment` remains a separate network check. Its stdin option `allowTurnstile: true` permits only the reviewed `challenges.cloudflare.com` challenge origin in script/frame/connect CSP checks; the default remains strict about external origins. Neither command proves a deployment's provider credentials, delivery, breach callback or complete abuse policy.
+
+### Localized email and abuse controls
+
+Pass `emailCopy: createEmailCopy({catalogues: {...}})` to a sender helper to customize bounded plain-text subjects and bodies. Catalogue entries must preserve every link/code placeholder. Account notices use the saved locale; anonymous flows use request language without revealing whether an account exists. Delivery failures for post-commit security notices do not roll back account changes; operators must monitor their sender.
+
+`AuthOptions.abuse` enables durable progressive password backoff and trusted-client/signup-domain velocity budgets. Configure the runtime trusted-proxy boundary before enabling client limits. Optional `createTurnstileChallenge` supplies a fixed-origin widget and bounded server verification; challenge success never overrides a hard budget. Provider callbacks and existing token redemption keep their own bound proofs.
+
+Auth pages use `Referrer-Policy: strict-origin`: path/query credentials are never sent as referrers, while browsers retain the Origin header needed for no-JavaScript POST forms. Null or foreign Origin headers remain rejected. Live pagination cursors use a process-local HMAC key; restart the search after a worker restart or changed boundary.

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security boundary
+
+This repository is an actively reviewed implementation, not an independent security assessment or a hostile multi-tenant authentication platform. Report a suspected vulnerability privately using the security reporting channel on the repository hosting this reviewed source; do not include passwords, session cookies, live recovery tokens or customer databases in public issues. If no private reporting channel is configured, ask the maintainer for one before sending sensitive details.
+
+## Trusted and untrusted components
+
+Operator modules, their dependencies, configuration, database directory, encryption/CSRF keys, identity providers and mail transport are trusted. Project routes and sandboxed guest code do not gain authority to load host modules. Core extension activation requires an explicitly supplied registry and a reviewed exact project revision pin. Never turn revision inspection into automatic approval.
+
+Auth is Node/SQLite only. It refuses unpatched SQLite versions and requires private database files. Keep the database, WAL/SHM, backups, operator modules and key files outside the application project and inaccessible to guest filesystem access. Do not run the host as a shared hostile operating-system user. Filesystem permission and symlink checks do not defend against an attacker who already controls the operator account or its parent directories.
+
+**Same-origin browser JavaScript is trusted.** HttpOnly cookies and stripped guest server headers do not isolate frontend JavaScript served on the account origin. Such JavaScript can fetch a CSRF value and send requests with ambient cookies. Serve only reviewed frontend content on that origin, or isolate the authentication surface on a different origin with explicit narrowly scoped integration. A WASM sandbox for server code is not a browser-content sandbox.
+
+## Authentication and authorization
+
+Use HTTPS with a canonical operator-specified origin, never an untrusted Host header. Cookies are Secure, HttpOnly and host-scoped. Unsafe HTTP operations require unambiguous same-origin and browser/session-bound CSRF proof. An XSS or compromised trusted dependency can cross this boundary; CSRF tokens do not prevent same-origin XSS.
+
+Session tokens are opaque and stored as hashes. TOTP/recovery/code consumption and administrative invariants use transactions. Role changes and account state changes invalidate relevant sessions. Fresh authentication, ceilings and last-administrator checks are service responsibilities, not UI-only safeguards. Use actor-token administrative methods for delegated users; unrestricted operator methods are not HTTP authorization APIs.
+
+Impersonation is opt-in, excludes privileged targets, expires, and denies account security/administrative mutations. The built-in account page shows a warning. Arbitrary guest pages do not automatically receive a universal impersonation banner; do not assume otherwise. Never expose an unrestricted issueSession or operator service method to a client.
+
+Metadata is never a permission source. Private fields must stay out of public projections; public/unsafe fields are untrusted. Render translated/user text as text, not markup. Operator theme inputs are constrained; arbitrary project templates are deliberately excluded.
+
+## Operational limitations
+
+Rate limits, worker bounds and request limits reduce specific abuse paths; they do not replace perimeter admission controls or deployment capacity testing. Review proxy/client identity configuration. Do not weaken MFA because an email/reset flow is inconvenient. Provider account linking must remain explicit and issuer/subject-scoped rather than inferred from matching email.
+
+Emails can fail or be delayed. Preserve an operator recovery procedure for deletion cancellations, email changes and provider outages. Do not log token-bearing callback URLs, passwords, codes, session headers or mail bodies. Development console/file senders intentionally expose development credentials and require explicit opt-in.
+
+Backups contain sensitive account records and password hashes. Preserve keys separately, retain the exact reviewed configuration, test isolated restores, and plan session/token revocation when restoring old data. An integrity check proves database consistency, not freshness, provenance or absence of malicious operator modifications. Key rotation is not a substitute for revoking compromised sessions or rotating other credentials.
+
+Synthetic tests do not prove real provider delivery, browser/device compatibility, accessibility conformance, production resilience, recovery time or independent security review. Keep those claims separate from local verification results.
+
+This repository follows the [core URLCode security policy](https://github.com/jimhoyd-com/urlcode/blob/main/SECURITY.md) for reporting and support baseline.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,29 @@
+# Bundled data attribution
+
+The disposable-email domain data comes from
+https://github.com/disposable-email-domains/disposable-email-domains at commit
+`be0dd1affed11ea9b1ffcd14da81319f9a080609`.
+
+Original file: `disposable_email_blocklist.conf` (8,883 entries).
+Original SHA-256: `87bf71873ced728237615c546eff8fa36962dfa261d366e13ef9e0bad3224aad`.
+The data is converted mechanically into a frozen TypeScript array; no upstream code
+is executed. The dataset is a fallible classification snapshot, not identity or
+abuse proof. Updates require a reviewed code change and configuration migration
+when the policy is enabled.
+
+Upstream license follows. URLCode auth code remains Apache-2.0 licensed.
+
+CC0 1.0 Universal (CC0 1.0)
+Public Domain Dedication
+
+No Copyright
+
+The person who associated a work with this deed has dedicated 
+the work to the public domain by waiving all of his or her rights
+to the work worldwide under copyright law, including all related
+and neighboring rights, to the extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even 
+for commercial purposes, all without asking permission.
+
+Details: https://creativecommons.org/publicdomain/zero/1.0/legalcode

package/THREAT-MODEL.md

@@ -0,0 +1,62 @@
+# Auth threat model
+
+## Scope and assets
+
+This package is a trusted Node host service. Application server code remains
+untrusted WASM under the core runtime's capability model. The auth service protects
+account ownership, verified identifiers, credential material, sessions, factor and
+recovery proofs, operator role grants, audit history and private profile data.
+SQLite files and backups contain sensitive account data: file permissions are a
+boundary, not whole-database encryption. TOTP secrets and protocol state are sealed;
+passwords are hashed, and reusable browser capabilities are stored as hashes.
+
+## Entry points and trust boundaries
+
+| Entry point | Untrusted input | Authority boundary |
+| --- | --- | --- |
+| Mounted auth HTTP routes | Query, form/JSON, cookies, origin, provider responses | Bounded parsing, browser binding, CSRF, maintained protocol verification, final SQLite transaction |
+| Public signup | Identifier, credential, profile and consent | Verification-first state machine; unique identifiers and reviewed default role; no metadata grants |
+| OIDC/WebAuthn completion | State, claims, signed assertions | Issuer/subject binding or RP/origin/UV checks; current account and credential versions rechecked at issuance |
+| Self-service security changes | Password/factor proof and session | Fresh non-impersonated authority; current version; atomic proof use and session revocation |
+| Email/manual recovery | Mailbox capabilities or reviewed case evidence | Explicit operator opt-in; cancellation/cooldown or two current administrators; restricted reenrollment |
+| Operator modules and CLI | Configuration, keys, import data, callbacks | Trusted operator installation outside the project; bounded imports; explicit configuration migration |
+| Auth service API called by admin | Actor token, target and reason | Worker rechecks current permissions, delegation ceiling, freshness and target state |
+
+A same-origin frontend can exercise browser authority even without reading an
+HttpOnly cookie. Do not host adversarial frontend scripts on this origin. A hostile
+host process, operator module, dependency or OS user able to read the key material
+is outside the WASM boundary. This release does not claim hostile multi-tenant
+readiness or independent assessment.
+
+## Required invariants
+
+- Guests cannot select host modules or receive session, provider or recovery secrets.
+- Required signup verification precedes stored credentials. Existing accounts are
+  never overwritten by a duplicate signup, linked by email alone, or upgraded from
+  untrusted metadata.
+- Proof verification and authority issuance must share account/credential version
+  checks; retries, parallel workers and A→B→A configuration changes cannot revive
+  consumed or stale authority.
+- A passkey cannot serve as both primary and second factor in the same sign-in.
+  Remembered-device authority never grants fresh admin/credential authority.
+- Recovery replacement-factor enrollment belongs to the restoration session.
+  Another party possessing an old password cannot win an enrollment race.
+- Administrative restoration is a human evidence procedure. Software enforces
+  two-person approval and delivery gates; it does not establish legal identity.
+- Limits fail closed, cleanup is bounded, and expiry is checked during use rather
+  than relying on a sweep. Network callbacks cannot authorize incomplete state.
+- Diagnostic output, public responses, browser JavaScript, tests and repository
+  artifacts must not contain real passwords, reusable credentials or customer data.
+
+## Review and evidence
+
+For an auth change, trace the final transaction, not just the form or preflight.
+Check replay, concurrency, expiry, browser/account binding, privilege changes,
+configuration migration, fallback methods, last usable access and secret handling.
+Run `npm run verify`; for exports/build/CLI changes also exercise the installed
+local tarballs across core/auth/admin. Protocol fixtures must use synthetic keys.
+
+Tests cover these mechanisms but are not a penetration test, real-provider setup,
+load/soak result or disaster-recovery exercise. Live Google/Apple/SES verification
+is separately deferred. Operator callbacks and policy data require their own
+review, monitoring, incident handling and periodically tested backups.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@jimhoyd/urlcode-auth",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jimhoyd-com/urlcode-auth.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "pretest": "node scripts/check-sqlite.mjs",
+    "test": "node --conditions=development --test test/*.test.ts",
+    "verify": "npm run typecheck && npm run build && npm test"
+  },
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "IMPLEMENTATION-STATUS.md",
+    "THIRD_PARTY_NOTICES.md",
+    "THREAT-MODEL.md"
+  ],
+  "devDependencies": {
+    "@types/node": "26.5.1",
+    "typescript": "6.0.3"
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "3.1135.0",
+    "@simplewebauthn/server": "14.0.2",
+    "bcryptjs": "3.0.3",
+    "jose": "6.2.12",
+    "openid-client": "6.8.8",
+    "otpauth": "9.5.2"
+  },
+  "peerDependencies": {
+    "@jimhoyd/urlcode": ">=0.4.0-alpha.1 <0.5.0",
+    "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.1 <0.2.0"
+  },
+  "bin": {
+    "urlcode-auth": "./dist/cli.js"
+  },
+  "homepage": "https://github.com/jimhoyd-com/urlcode-auth#readme",
+  "bugs": {
+    "url": "https://github.com/jimhoyd-com/urlcode-auth/issues"
+  }
+}