@jimhoyd/urlcode-admin 0.1.0-alpha.1

package/IMPLEMENTATION-STATUS.md

@@ -0,0 +1,28 @@
+# Admin implementation status
+
+Status: `0.1.0-alpha.1`, the first npm alpha, published through the tag-driven release workflow after core `0.4.0-alpha.1`, ui `0.1.0-alpha.1` and auth `0.1.0-alpha.1` (core issue #78). The implemented admin workflows and reviewed shared-presentation work are merged to main. Production release validation remains separate. Cross-repository acceptance: https://github.com/jimhoyd-com/urlcode/issues/58. Core extension integration PR #59 is merged. Auth owns identities, sessions and transactional authority checks; this package owns the trusted administration interface.
+
+Implemented: scoped internal authorization; no impersonated admin access; fresh, reasoned mutations; account search, compound filters, sorting, stable live pagination, details, setup invitation and bounded export; audited full-email reveal; lock/unlock/role assignment; global and individual session revocation; role definitions; audit pagination; registration approval; dual-approval security cases with notes/closure; opt-in short-lived impersonation with required notice; shared safe presentation; auth/admin initialization with private operator storage.
+
+## Additional implemented acceptance
+
+- Complete filtered-user exports (5,000 records/4 MiB/5 seconds, all-or-nothing), full-range audit exports, staged bulk role/verification and individual verification/password-reset/email-change/deletion/method-removal workflows.
+- Structured account detail sections for overview, methods, sessions, recovery, activity and consent/data; escaped administrator notes are audited. Method operations are a linked fresh-authentication view.
+- Manual recovery evidence, two distinct authorized reviewers, private delivery to replacement address and warning to old address, browser redemption and mandatory factor reenrollment. This is not automated identity verification; recovery contacts/public intake remain later auth scope.
+- Shared localized email copy, typed health adapter, host support-banner wrapper, and synthetic browser walkthrough of dashboard/search/detail.
+- Embedded hosts can use `createAdministrationRuntime` to install the support banner and live runtime health together; an actual-runtime regression verifies cached application pages, impersonation, revocation and admin denial. Every request must use the returned runtime. The stock CLI still requires host integration; arbitrary frontend scripts remain outside the trusted UI guarantee.
+- Session account/device/created-time filters, persisted passkey/provider added/last-used dates, and dashboard linked totals/SVG activity charts. Historic method timestamps remain unknown rather than being invented.
+- Kit adoption (urlcode-admin issue #10, core plan §7.2) is implemented: every console screen is an `admin/*` kit template with a declared view model and sample view (`adminTemplates`, `adminUiTemplates`); `adminExtension({ ui })` renders through `ui.kit` when the host supplies the `ui` extension and through the shared primitives inside the console shell 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, the strict CSP, `no-store` and the immutable hashed stylesheet. The compact UI pass supplies the console shell, sidebar icons, metrics, tables, forms and theme toggle through the pinned shared UI stylesheet. Both kit and primitive paths have clean-install checks and a local light/dark browser walkthrough; broader accessibility and device assessment remains separate.
+
+## Remaining first-release acceptance
+
+- Connect live operator runtime/provider/sender observations to the health adapter. Activity data begins when the feature is activated.
+- Full accessibility assessment and broader browser/device/deployment validation. The current walkthrough is not WCAG conformance evidence.
+- Refresh package and CI evidence whenever code or dependency pins change. The private auth/UI credentials are configured, core #64/#69 are closed, and hosted verification passes on Node 22/24/26. See ACCEPTANCE.md for the exact baseline.
+
+Role definitions remain reviewed operator configuration. User role assignments are administrative transactions. This preserves the separation between changing authority definitions and assigning already-reviewed authority.
+
+## Recorded acceptance
+
+See [ACCEPTANCE.md](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,292 @@
+# URLCode admin
+
+An optional administration extension backed by URLCode auth's service API. It supplies permission-gated pages for accounts, roles, sessions, audit records, registration approvals, administrative cases and explicit support impersonation. It does not replace URLCode's private runtime management endpoints or edit project YAML.
+
+[![Verify](https://github.com/jimhoyd-com/urlcode-admin/actions/workflows/verify.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode-admin/actions/workflows/verify.yml)
+
+This is an actively reviewed Node/SQLite implementation. Still outstanding: live operator runtime/provider/sender observations feeding the health adapter, a full accessibility and broader browser/device/deployment assessment, and refreshed package/CI evidence whenever code or dependency pins change. Local tests are not independent security review, real-provider deployment evidence or an accessibility certification. See [SECURITY.md](SECURITY.md).
+
+## Install
+
+```sh
+npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/urlcode-admin
+npx urlcode init my-site --with auth,admin
+```
+
+`@jimhoyd/urlcode-admin` is published to npm as an alpha (`0.1.0-alpha.1`). Alpha releases can change exported names, the console's routes and the scaffold output between versions without a deprecation period; pin exact versions in an operator directory and read the release notes before upgrading. The package declares its peers by version range (`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0`, `@jimhoyd/urlcode-ui` and `@jimhoyd/urlcode-auth >=0.1.0-alpha.1 <0.2.0`), so install all four together; npm resolves them from the registry. Every release is built by the tag-driven [release workflow](.github/workflows/release.yml), signed with a GitHub attestation and published through npm trusted publishing, so `gh attestation verify jimhoyd-urlcode-admin-<version>.tgz --repo jimhoyd-com/urlcode-admin` and `npm audit signatures` can check what you downloaded. Publishing is still not a security review, real-provider deployment evidence or an accessibility certification.
+
+## Build from reviewed local repositories
+
+The published packages are the supported path; building from source remains available for deployments that must review and pin exact commits rather than registry versions. The core runtime must include the reviewed generic extension contract from [core PR #59](https://github.com/jimhoyd-com/urlcode/pull/59) or an approved successor; the version number `0.3.0` alone is insufficient. Use an exact reviewed core commit and clean committed source trees.
+
+```sh
+node scripts/pack-sources.mjs \
+  --core /absolute/source/urlcode \
+  --auth /absolute/source/urlcode-auth \
+  --ui /absolute/source/urlcode-ui \
+  --admin /absolute/source/urlcode-admin \
+  --out /absolute/new-private-package-directory
+```
+
+`--core-revision` defaults to the `urlcode` entry of [`peers.json`](peers.json), the single record of the exact core/auth/UI revisions verified with this source checkout (source CI and [ACCEPTANCE.md](ACCEPTANCE.md) read the same file; published releases resolve peers from the registry by version range instead); pass it explicitly to pack against another reviewed commit. The helper runs lockfile installation without lifecycle scripts, installs the peers from locally built tarballs instead of the registry, typechecks/builds, packs and records commit/integrity metadata. Nothing is published. `--offline` requires an existing dependency cache; `--skip-install` reuses third-party dependencies. Neither bypasses the reviewed revision/clean-tree requirement. Run each repository's full `npm run verify` separately.
+
+Install the resulting core, UI, auth and admin tarballs together in your operator directory, using filenames recorded in `source-manifest.json`. Follow auth's scaffold/bootstrap procedure first, or run `urlcode-admin init --directory NEW_DIRECTORY`, which wires both auth and admin into the generated host and route project; review the result before activation.
+
+## Wiring
+
+Declare the additional logical extension and its exclusive mount:
+
+```yaml
+extensions:
+  admin:
+    version: '1'
+    config: {}
+routes:
+  /admin/*:
+    extension: admin
+    methods: [GET, HEAD, POST]
+```
+
+Merge these entries into the existing versioned auth project, then review and update the static project revision pin. In the trusted external host:
+
+```js
+import {authExtension} from '@jimhoyd/urlcode-auth';
+import {adminExtension} from '@jimhoyd/urlcode-admin';
+
+// service, csrfKey and reviewed projectSha256 are operator-owned values.
+export default {
+  extensions: [
+    authExtension({service, csrfKey, projectSha256}),
+    adminExtension({service, csrfKey, projectSha256, authMount: '/account'}),
+  ],
+  async close() { await service.close(); },
+};
+```
+
+The snippet is an integration fragment; use the auth scaffold's private key/service setup and required HTTPS origin rather than inventing credentials. Use the same CSRF key and shared service. No auth package is loaded from application YAML. Runtime activation uses the explicit external host and matching canonical `--origin`.
+
+Administrative actions authenticate internally even without an extra route policy. Missing sessions or administrative permissions receive 404 at the console gate. Use operator role declarations with the actual permissions exported by this implementation: `auth.users.read`, `auth.users.reveal`, `auth.users.export`, `auth.users.manage`, `auth.users.create`, `auth.sessions.manage`, `auth.roles.read`, `auth.audit.read`, `auth.cases.read`, `auth.cases.manage`, and `auth.users.impersonate`. `*` grants full operator-defined administrator permissions. Do not copy the proposal's separate `admin.*` permission names and expect them to work automatically.
+
+## Operating the console
+
+Bootstrap the first administrator through auth's operator CLI using JSON stdin. Writes require recent authentication and a reason; role/status/session changes run through the auth service's transactional authority checks. Roles themselves remain operator configuration. Masked lists, pagination, permission-filtered navigation and audit records help limit routine exposure.
+
+Cases currently model bounded, two-person approval of specific administrative changes with target-version checks. They are not a complete lost-everything identity-verification process. Establish an operator evidence procedure before using factor-reset cases. The console does not supply all proposed notes, close/reject, requester evidence or reporting workflows.
+
+Impersonation requires explicit service opt-in, a dedicated permission and a `notifyImpersonation` callback. If the required notification fails, the issued session is revoked before returning it. Impersonation expires and cannot perform fresh account-security/admin changes. The account page shows a warning; arbitrary guest application pages do not automatically show a banner. Ending impersonation requires signing back in as the operator.
+
+Optional presentation and invitation/notification callbacks are operator-owned integrations. No real SES, Google or Apple account is provisioned by this package. Keep keys and database backups outside the application project, retain matching configuration, and close the shared service only once after both extensions stop.
+
+Apache-2.0. `scripts/pack-sources.mjs` only packs; publication happens exclusively through the tag-driven release workflow.
+
+## New local installation
+
+After installing the packages (from npm or the reviewed local tarballs), run `urlcode-admin init --directory /absolute/new/site`. It creates a private operator host and database key directory outside the route project, with registration off and auth/admin mounts configured. Follow the generated README to bootstrap the first administrator, configure HTTPS and approve the project revision. This does not deploy or send mail.
+
+## Programmatic scaffold
+
+`scaffold(request)` is the contract core's `urlcode init --with auth,admin` calls on each installed `@jimhoyd/urlcode-<name>` package; auth and admin export the same shape. It describes admin's contribution and never writes:
+
+```ts
+import {scaffold} from '@jimhoyd/urlcode-admin';
+const result = await scaffold({directory, project, hostFile, names: ['auth', 'admin']});
+// result.extensions -> {admin: {version: '1', config: {}}}
+// result.routes     -> {'/admin/*': {extension: 'admin', methods: ['GET', 'HEAD', 'POST']}}
+// result.hostImports, result.hostSetup, result.hostEntries -> lines for host.mjs
+// result.files -> [] ; result.readme -> "## Administration" section ; result.nextSteps
+```
+
+Admin contributes the `admin` extension block, the `/admin/*` mount, one `adminExtension({service, csrfKey, projectSha256, authMount: '/account'})` host entry and a README section. It writes no key files and defines no environment: the `service`, `csrfKey` and `projectSha256` identifiers its host entry references are defined by auth's host setup, so `names` must include `auth` (the call refuses otherwise). The caller merges each result's `extensions` and `routes` into one `urlcode.yaml`, concatenates host imports, setup and entries in order, and appends the README sections. `urlcode-admin init` composes this result with auth's initializer and produces the same files it always did. Types `ScaffoldRequest`, `ScaffoldFile` and `ScaffoldResult` are exported.
+
+## Private dependency CI
+
+Source verification runs automatically for pull requests and pushes to main, and can also be dispatched manually. It checks out the exact core/auth/UI revisions recorded in [`peers.json`](peers.json) (a single workflow step reads the file and later steps use its outputs) and runs Node 22/24/26. `npm test` first runs `scripts/check-sqlite.mjs`, which exits with the SQLite requirement and the bundled version named when the Node release lacks a patched SQLite (3.51.3+, or 3.50.7+/3.44.6+ within those lines), the same rule auth's store enforces at runtime. The approved read-only credentials are `URLCODE_AUTH_READ_TOKEN` and `URLCODE_UI_READ_TOKEN`; deploy keys remain disabled by repository policy. Credentials are not persisted by checkout. Fork pull requests do not receive repository secrets and cannot complete private dependency checkout; they require a reviewed maintainer branch. Do not switch to `pull_request_target` to run untrusted changes with secrets, reuse broad personal tokens, or weaken repository policy. Local full verification and source-package smoke tests remain usable without CI credentials.
+
+Releases are separate: pushing a `v<version>` tag whose commit is on `main` and whose version equals `package.json` runs the [release workflow](.github/workflows/release.yml), which installs the three peers from the registry at the lower bound of each declared range, runs the same `npm run verify`, audits production dependencies, packs, attests the tarball, publishes to npm through trusted publishing when the repository variable `PUBLISH_NPM` is `true`, and creates the GitHub release with the tarball attached.
+
+### Operator health observations
+
+Pass `health: async ({ signal }) => snapshot` to `adminExtension` to expose the
+permission-gated `/admin/health` page (`auth.health.read`). The callback reads your
+trusted runtime/provider monitoring integration; the admin package does not fetch
+project-supplied URLs or reuse management credentials. Its two-second deadline
+aborts the signal, and at most one callback remains in flight even if an adapter
+ignores cancellation. A failed or malformed observation returns an unavailable
+status without exposing the original error.
+
+```ts
+health: async ({ signal }) => ({
+  checkedAt: new Date().toISOString(),
+  runtime: { status: 'healthy', readiness: 'healthy', version: '0.3.0', routes: 12 },
+  sender: 'unknown',
+  providers: [{ id: 'google', status: 'unknown' }],
+  alerts: [],
+})
+```
+
+The example shows the shape, not a production probe. Populate it from measured
+operator observations. Status values are `healthy`, `degraded`, `unavailable`, or
+`unknown`. Alert codes are `sender-failed`, `provider-expiring`,
+`presentation-outdated`, and `translation-incomplete`. No provider messages,
+credentials, account identifiers or arbitrary metadata are returned. The timestamp
+makes the age of an observation visible; live provider checks remain a separate
+operator acceptance task.
+
+Audit readers with both `auth.audit.read` and `auth.audit.export` can download a
+complete selected UTC range as JSON at `/admin/audit/export?from=...&to=...`.
+Actor, subject and action filters apply to every page. The export rechecks the
+session and permissions while reading and before returning the result. Requests
+above 5,000 events, 4 MiB, or five seconds fail with a request to narrow the range;
+they never silently return a partial file. Export timestamps are bounded at the
+start of the request. Audit retention still limits the available history.
+
+The users page supports searches by full or masked email, display name, or account ID; role, status, stored credential method (password, passkey, or external identity), mailbox verification, locale, and UTC creation/activity ranges; and ascending or descending sorting. The verified filter describes mailbox proof. Email-code availability is a deployment setting, not a stored per-user credential method. Text matching uses SQLite's built-in case handling, which is case-insensitive for ASCII letters.
+
+Filters and sort order carry through pagination and the bounded, audited CSV page export (at most 50 accounts). Email remains masked in tables, JSON lists and CSV. Pagination is live rather than a database snapshot: if the boundary account is deleted or its sort value changes, restart the search. Cursors contain opaque identifiers and hashes, never full email or display-name sort values. Last-seen values use retained device and session activity, not a complete historical activity log; deleted or expired records can change that view.
+
+An account's full email can be revealed only through the explicit **Reveal email address** action, with `auth.users.read` and `auth.users.reveal`, a fresh session, and a reason. The service rechecks the actor's authority and target restrictions and records an audit event. The response remains non-cacheable; routine lists and exports remain masked.
+
+### Support-session banner integration
+
+Before enabling impersonation, route every application response through
+`withSupportBanner(runtime, { service, authMount: '/account' })` in your trusted
+host. It wraps the `Runtime` returned by core `createRuntime`; your host must call
+the wrapped `handle` for every route. It uses the current auth session to mark HTML
+pages, links to the trusted account page to end the session, disables conditional
+and compressed delivery, and forces no-store on support-session responses. It does
+not send credentials or actor identity to application code.
+
+```ts
+import { createRuntime } from '@jimhoyd/urlcode';
+import { withSupportBanner } from '@jimhoyd/urlcode-admin';
+const runtime = withSupportBanner(
+  await createRuntime(project, { origin, extensions }),
+  { service, authMount: '/account' },
+);
+// The host routes every request through runtime.handle(request).
+```
+
+HTML that remains compressed, is invalid UTF-8 or exceeds the configured bound
+(default 1 MiB) is replaced with a support-session interstitial. Non-HTML responses
+carry the support marker and no-store headers. Copy can be localized with the
+bounded `message`/`endLabel` options. Use trusted frontend content: arbitrary app
+CSS/JavaScript can hide or alter any DOM notice. Alternate host paths, upstream
+caches and the stock CLI do not install this wrapper automatically; validate the
+actual host integration before turning impersonation on.
+
+The user directory offers both current-page CSV and **all matching accounts** CSV. Complete export preserves the selected filters and sort, starts at the beginning, and buffers its result privately: more than 5,000 accounts, 4 MiB or five seconds fails with an instruction to narrow filters, without a partial download. Each included subject passes fresh actor/target export authorization and produces its own audit event; failure can leave those audit events even though no file is returned. Read/export permission is checked again before release. CSV masks email identifiers and escapes formula-like cells. This is live cursor pagination, not a database-wide snapshot: concurrent changes can require restarting and new matching rows can appear or disappear during the operation. A timed-out in-flight trusted service operation may finish auditing, but the helper schedules no further work and returns no data.
+
+Account details expose linked overview, method administration, sessions, recovery,
+activity and consent/data sections. Administrator notes are bounded, escaped
+`admin.note` audit events; viewing them requires audit-read authority. Session
+search filters by account, device label and UTC creation range before pagination.
+Method inspection exposes recorded added/last-used timestamps, never provider
+subjects or credential key material. Historical timestamps are shown as unknown.
+
+### Integrated host runtime
+
+For an embedded host, use `createAdministrationRuntime` instead of constructing
+and wrapping the runtime separately. It mounts auth and admin using the same
+operator service, CSRF key and revision pin, automatically decorates support
+responses, and reports the runtime's observed health/version/route count.
+
+```ts
+import {createAdministrationRuntime} from '@jimhoyd/urlcode-admin';
+
+const runtime = await createAdministrationRuntime(projectDirectory, {
+  auth: {service, csrfKey, projectSha256},
+  runtime: {origin: 'https://accounts.example.com'},
+  admin: {notifyImpersonation},
+  observations: async ({signal}) => ({
+    sender: 'unknown', providers: [], alerts: [],
+  }),
+});
+// Forward every request through runtime.handle(), including public app routes.
+// On shutdown: await runtime.close(); await service.close();
+```
+
+Impersonation still requires the service's explicit opt-in and a successful
+notification callback. The constructor does not open a listening socket, enable
+public registration, probe live providers or change project YAML. Your host owns
+the auth service lifecycle; closing this runtime does not close that shared
+service. Additional trusted extensions can be supplied in `runtime.extensions`.
+Use `admin.authMount` when the auth mount differs from `/account`.
+
+The health panel's readiness reflects this runtime's `healthy` state, not an
+external load balancer, database recovery drill or delivery guarantee. Optional
+sender/provider observations pass through the existing bounded, redacted health
+adapter. When omitted those external states remain unknown. The standalone core
+CLI still needs custom host integration for universal support banners; this
+constructor is the supported embedded-host path.
+
+## Shared UI dependency
+
+Install `@jimhoyd/urlcode-ui` alongside core before installing this package (npm
+does this when all four packages are installed together). The UI peer owns document layout, semantic fields, escaping, themes
+and the locale engine; authentication/administration behavior remains here.
+`scripts/pack-sources.mjs` now requires `--ui /absolute/path/to/urlcode-ui` and
+builds the UI archive before its consumers. Core can use UI without auth/admin.
+Cross-repository source CI needs the narrow `URLCODE_UI_READ_TOKEN`; releases
+resolve the published package instead, and no broad credential is used as a
+workaround.
+
+## Presentation
+
+Every console screen is an `admin/*` template in the urlcode-ui kit language with a
+declared view model (`adminTemplates`, each with a sample view; `adminUiTemplates` is
+the block the `ui` extension takes): dashboard, users, user-detail, sessions, roles,
+audit, registrations, cases, health, recovery-cases, account-operations, reveal and
+status. The extension computes the view and the template only places it: a template
+cannot change a flow, which permission gates a control, the freshness or reason gate
+on a mutation, what is escaped, or the CSRF field and headers a page sends. Forms,
+table rows, charts and icons arrive in the view as renderer-produced markup built by
+the shared primitives.
+
+`adminExtension` takes an optional `ui`, the object `createUiExtension` returns.
+Declare `ui` first in the host file so the runtime activates it before auth and
+admin; admin 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';
+import { adminExtension, adminUiTemplates } from '@jimhoyd/urlcode-admin';
+const ui = createUiExtension({ projectSha256, projectRoot: '/absolute/site', sources: [authCatalogue], extensions: [authUiTemplates, adminUiTemplates] });
+export default { extensions: [ui.registration, authExtension({ service, csrfKey, projectSha256, ui }), adminExtension({ 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`: the project's theme, layout, hashed
+stylesheet and copy apply, the console navigation becomes the layout's primary
+navigation and account menu, a project file `ui/templates/admin/<screen>.html`
+shadows the shipped template, and `urlcode-ui doctor` reports every `admin/*`
+template behind its view model. Copy then resolves through the kit's presentation
+composed with the admin catalogue: register `authCatalogue` in `sources` (the kit's
+catalogue holds at most 512 keys, so it cannot also take `adminCatalogue`; admin
+composes its own copy on top) and omit `presentation`. If both are given,
+`presentation` wins.
+
+Without `ui`, nothing changes: screens render the same templates through the shared
+primitives inside the console shell, 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.
+
+Use `createAdminPresentation` when translating console-specific copy without the
+kit. It composes bounded auth and admin catalogues while keeping account workflows
+out of URLCode UI. Existing `presentation` instances remain supported; untranslated
+new messages fall back to English.
+
+```js
+import {createAdminPresentation} from '@jimhoyd/urlcode-admin';
+const presentation = createAdminPresentation({
+  catalogues: {fr: {'adminUi.noSessions': 'Aucune session active.'}},
+});
+// Pass presentation to adminExtension, or the admin options of createAdministrationRuntime.
+```
+
+See [UX-REVIEW.md](./UX-REVIEW.md) for reviewed screens, changes and validation limits.

package/SECURITY.md

@@ -0,0 +1,19 @@
+# Security boundary
+
+The admin console is a privileged client of URLCode auth's service API. Its operator modules, dependencies, service instance, keys and notification transport are trusted. It is not a replacement for the runtime's separately credentialed infrastructure management endpoints, and it does not make a hostile multi-tenant deployment safe.
+
+Use the reviewed core extension contract and an explicit static project revision pin. Host modules and database/key files belong outside the application project. Use Node with patched SQLite, HTTPS and a canonical operator-provided origin. Share the auth service and CSRF key intentionally; do not discover plugins or database credentials from project YAML.
+
+Same-origin frontend scripts share browser authority. HttpOnly cookies and server guest-header filtering do not prevent such scripts from obtaining CSRF proof and issuing authenticated requests. Auth/admin must run beside trusted frontend content or on a separately isolated origin. Restrictive response CSP does not repair other compromised pages on the same origin.
+
+Every delegated mutation must use an actor-token auth service method. UI hiding is not authorization. The service rechecks current privileges, freshness, delegation ceilings, target version/state and last-administrator constraints inside transactions. Do not expose unrestricted operator APIs through generic HTTP dispatch. Account metadata and role names supplied by users never grant permissions.
+
+Case approval requires distinct authorized actors and a current target. A two-person approval transaction is not identity proof: establish a documented human evidence procedure for account recovery. Keep meaningful reasons and protect the audit trail. Review permissions before assigning support roles.
+
+Impersonation is explicit and bounded, excludes privileged targets, and cannot perform security/admin step-up actions. Notifications are required before returning a usable impersonation session. The built-in account page carries a warning; arbitrary guest pages do not automatically show one. Do not claim universal banners or use impersonation as a substitute for least-privilege diagnostic tooling.
+
+Protect database backups, audit exports, operator stdin and notification records as sensitive data. Never post passwords, tokens, keys or live customer database files in public issues. Report vulnerabilities using the repository's private security reporting channel; if none is configured, request a private contact before sharing sensitive evidence.
+
+Passing tests do not establish independent assessment, real-provider compatibility, production recovery/soak behavior or WCAG conformance. Track those checks separately. The console's partial reporting and case workflows should not be described as completion of every item in the design proposal.
+
+This repository follows the [core URLCode security policy](https://github.com/jimhoyd-com/urlcode/blob/main/SECURITY.md) for reporting and support baseline.

package/THREAT-MODEL.md

@@ -0,0 +1,34 @@
+# Admin threat model
+
+The console is a privileged client of the separate auth service. Its main assets
+are user ownership and access, identifiers, private exports, recovery evidence,
+operator authority and the audit trail. The operator host, installed modules and
+notification integration are trusted; route projects and all request fields are
+untrusted. Run beside trusted frontend content or use an isolated origin.
+
+| Threat | Enforced boundary |
+| --- | --- |
+| Hidden UI controls bypassed through direct requests | Per-operation permissions plus service-side transactional authorization |
+| Stolen, stale or remembered-device session used for mutations | Fresh real authentication; current roles and account state; impersonation/restricted-session denial |
+| Support operator modifies a more privileged account | Delegation ceiling, self-mutation restrictions and last-administrator checks |
+| Recovery reviewer restores the wrong account or colludes | Evidence recorded for a human procedure, distinct current approvers, target/actor versions, private delivery gate and audit; colluding authorized operators remain a trust risk |
+| Identifier or export leakage | Masked defaults, non-PII cursors, audited reveal/export, no-store responses, bounded authorized exports |
+| HTML, CSV or log injection | Escaped markup, plain evidence, neutralized spreadsheet cells and no raw provider exceptions |
+| Impersonation used as a credential/admin bypass | Explicit opt-in, notice, short expiry, restricted authority, no security step-up |
+| Operator callback stalls or misbehaves | Time/size/concurrency bounds and no activation before required delivery succeeds |
+
+Every privileged write must be checked in the auth service's transaction. UI hiding,
+CSRF and a prior role lookup are necessary context but do not replace that check.
+Retain meaningful reasons and limit access to case notes and evidence. A case
+reference is plain text: the console must not fetch uploaded URLs or pretend that
+a two-person approval proves identity automatically.
+
+Changes must test denied and racing requests, revocation and stale approvals,
+partial delivery, masked outputs, typed bulk confirmations and all-or-nothing
+operations. Run `npm run verify` and cross-package installed-consumer checks for
+package/initializer changes. Review SECURITY.md and IMPLEMENTATION-STATUS.md.
+
+Known deployment limits remain explicit: universal guest-page impersonation banners
+require application integration; live providers and independent security,
+accessibility, recovery and load/soak validation are separate evidence. CI cannot
+establish those properties. No hostile multi-tenant readiness is claimed.