Admin console

An internal console for your team: find a customer, see their account, act on it and sign in as them, with every action recorded.

This is an app part spec on Spekkr, published by vex. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
vex/admin-console
Version
0.1.2
Published by
vex
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/vex/admin-console/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by vex.

What does the result look like?

Admin console: harbor searchAdmin console: harbor accountAdmin console: harbor impersonationAdmin console: harbor records 360

What can I customize?

Database

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

    Admin console

    What this builds

    The pages a company's own staff use to help its customers: find an account, see what is in it, fix what can be fixed, and look at the app as the customer does. The console is kept apart from the app, shows no more than the job needs, and records everything staff do in it.

    Read spekkr.inputs.json first. impersonation decides whether R6 exists, and a session as a customer lasts impersonation_minutes minutes. require_reason changes R5 and R6.

    This spec needs an app with a users table and sign-in. It does not build them.

    Out of scope

    • A general tool for editing any row of any table.
    • Charts and reports.
    • Help-desk tickets.

    Requirements

    Each requirement has an id. Tests name the id they cover.

    R1. Who is staff
    • Staff are listed in a table of their own, with a role: support or admin.
    • A person becomes staff by a command run on the server, or by an admin in the console. No public route and no field on a form can make someone staff.
    • An admin cannot remove their own role, and the last admin cannot be removed.

    Accept when: a request that sets a role field on the user's own profile changes nothing, and removing the last admin is refused.

    R2. Kept apart
    • Every console address starts with /admin and passes through one guard.
    • A person who is not staff gets 404 for every console address, the same answer as for an address that does not exist.
    • The console asks staff to sign in again if they last did so more than 12 hours ago.
    • A test lists every route under /admin and fails if one is not behind the guard.

    Accept when: a signed-in customer gets 404 for each console address, and the route test fails when a route is added outside the guard.

    R3. Find a customer
    • Staff search by email address, name or id. An exact email or id leads straight to the account.
    • Results show a name, a masked email address and when the account was made, 20 at a time.

    Accept when: a search by part of a name lists matching accounts with their email addresses masked.

    R4. A customer's page
    • The page is made of sections, each a function that takes the account and returns facts to show. The first sections: the account, its sessions, its workspaces if the app has them.
    • Personal details are masked: s•••@example.com. "Show" reveals one, and the reveal is recorded.
    • The page shows the last 20 things staff did to this account.

    Accept when: the page as first loaded holds no whole email address, and pressing "Show" leaves a record.

    R5. Actions
    • Actions are a list in code. Each has a name, the role it needs, whether it asks to be confirmed, and a function that does it.
    • The first actions: suspend an account, lift a suspension, end all of an account's sessions, and resend the confirmation email.
    • If require_reason is on, every action needs a reason of at least 10 characters before it runs.
    • A suspended account cannot sign in or use a session it has. Its sign-in page says the account is suspended and how to reach support.
    • support can do only the actions marked for it. admin can do all.

    Accept when: a support person gets 403 for an admin action, a suspended account's existing session is refused on its next request, and with require_reason on, an action without a reason does not run.

    R6. Sign in as a customer

    Only if impersonation is on.

    • Staff start a session as a customer from the customer's page. If require_reason is on, it needs a reason.
    • The session lasts impersonation_minutes minutes and then ends by itself. A banner on every page of the app says "You are signed in as NAME" and has a button to stop.
    • In such a session the routes marked sensitive answer 403: changing the email address or the password, deleting the account, anything that pays or changes how the customer pays, and creating API keys.
    • Staff cannot sign in as other staff. A session as a customer cannot open the console or start another such session.
    • The customer's own sessions are untouched, and nothing the customer sees says that staff looked.
    • Whatever is recorded during the session, by this spec or by the app, names the staff member as well as the customer.

    Accept when: a sensitive route answers 403 in such a session, the session stops working one second after its time, and staff trying to sign in as staff get 403.

    R7. Everything is recorded
    • Each action, each reveal and the start and end of each session as a customer is recorded: who, what, on which account, the reason, when, and from which IP address.
    • Records cannot be changed or deleted from the console.
    • An admin can read all records, with filters for staff member and account.

    Accept when: each of the four kinds of event leaves a record with every field, and no console route changes one.

    R8. Pages
    • Search, the customer's page, the staff list, the records.
    • Every page says in its header that it is the console, in a colour the app does not use, so staff never mistake one for the other.

    Accept when: each page works with a keyboard alone and at a 360 pixel wide screen.

    Definition of done

    • Every acceptance check above has an automated test, and all tests pass.
    • A README explains how to make the first admin, how to add a section and an action, how to mark a route sensitive, and how to run the tests.
    # Admin console
    
    ## What this builds
    
    The pages a company's own staff use to help its customers: find an account, see
    what is in it, fix what can be fixed, and look at the app as the customer does.
    The console is kept apart from the app, shows no more than the job needs, and
    records everything staff do in it.
    
    Read `spekkr.inputs.json` first. `impersonation` decides whether R6 exists, and a
    session as a customer lasts `impersonation_minutes` minutes. `require_reason`
    changes R5 and R6.
    
    This spec needs an app with a `users` table and sign-in. It does not build them.
    
    ## Out of scope
    
    - A general tool for editing any row of any table.
    - Charts and reports.
    - Help-desk tickets.
    
    ## Requirements
    
    Each requirement has an id. Tests name the id they cover.
    
    ### R1. Who is staff
    
    - Staff are listed in a table of their own, with a role: `support` or `admin`.
    - A person becomes staff by a command run on the server, or by an `admin` in the
      console. No public route and no field on a form can make someone staff.
    - An `admin` cannot remove their own role, and the last `admin` cannot be
      removed.
    
    Accept when: a request that sets a role field on the user's own profile changes
    nothing, and removing the last `admin` is refused.
    
    ### R2. Kept apart
    
    - Every console address starts with `/admin` and passes through one guard.
    - A person who is not staff gets 404 for every console address, the same answer
      as for an address that does not exist.
    - The console asks staff to sign in again if they last did so more than 12 hours
      ago.
    - A test lists every route under `/admin` and fails if one is not behind the
      guard.
    
    Accept when: a signed-in customer gets 404 for each console address, and the
    route test fails when a route is added outside the guard.
    
    ### R3. Find a customer
    
    - Staff search by email address, name or id. An exact email or id leads straight
      to the account.
    - Results show a name, a masked email address and when the account was made, 20
      at a time.
    
    Accept when: a search by part of a name lists matching accounts with their email
    addresses masked.
    
    ### R4. A customer's page
    
    - The page is made of sections, each a function that takes the account and
      returns facts to show. The first sections: the account, its sessions, its
      workspaces if the app has them.
    - Personal details are masked: `s•••@example.com`. "Show" reveals one, and the
      reveal is recorded.
    - The page shows the last 20 things staff did to this account.
    
    Accept when: the page as first loaded holds no whole email address, and pressing
    "Show" leaves a record.
    
    ### R5. Actions
    
    - Actions are a list in code. Each has a name, the role it needs, whether it asks
      to be confirmed, and a function that does it.
    - The first actions: suspend an account, lift a suspension, end all of an
      account's sessions, and resend the confirmation email.
    - If `require_reason` is on, every action needs a reason of at least 10
      characters before it runs.
    - A suspended account cannot sign in or use a session it has. Its sign-in page
      says the account is suspended and how to reach support.
    - `support` can do only the actions marked for it. `admin` can do all.
    
    Accept when: a `support` person gets 403 for an `admin` action, a suspended
    account's existing session is refused on its next request, and with
    `require_reason` on, an action without a reason does not run.
    
    ### R6. Sign in as a customer
    
    Only if `impersonation` is on.
    
    - Staff start a session as a customer from the customer's page. If
      `require_reason` is on, it needs a reason.
    - The session lasts `impersonation_minutes` minutes and then ends by itself.
      A banner on every page of the app says "You are signed in as NAME" and has a
      button to stop.
    - In such a session the routes marked sensitive answer 403: changing the email
      address or the password, deleting the account, anything that pays or changes
      how the customer pays, and creating API keys.
    - Staff cannot sign in as other staff. A session as a customer cannot open the
      console or start another such session.
    - The customer's own sessions are untouched, and nothing the customer sees says
      that staff looked.
    - Whatever is recorded during the session, by this spec or by the app, names the
      staff member as well as the customer.
    
    Accept when: a sensitive route answers 403 in such a session, the session stops
    working one second after its time, and staff trying to sign in as staff get 403.
    
    ### R7. Everything is recorded
    
    - Each action, each reveal and the start and end of each session as a customer is
      recorded: who, what, on which account, the reason, when, and from which IP
      address.
    - Records cannot be changed or deleted from the console.
    - An `admin` can read all records, with filters for staff member and account.
    
    Accept when: each of the four kinds of event leaves a record with every field,
    and no console route changes one.
    
    ### R8. Pages
    
    - Search, the customer's page, the staff list, the records.
    - Every page says in its header that it is the console, in a colour the app does
      not use, so staff never mistake one for the other.
    
    Accept when: each page works with a keyboard alone and at a 360 pixel wide screen.
    
    ## Definition of done
    
    - Every acceptance check above has an automated test, and all tests pass.
    - A README explains how to make the first `admin`, how to add a section and an
      action, how to mark a route sensitive, and how to run the tests.
    

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    Data model

    Use the database in the database input.

    TableColumns
    staffuser_id (primary key), role, added_by, added_at
    staff_recordsid, staff_id, kind, account_id, detail (JSON), reason, ip, at
    impersonationsid, staff_id, account_id, token_hash (unique), reason, started_at, expires_at, ended_at (only if impersonation is on)

    users gains suspended_at. kind is one of action, reveal, impersonation_started and impersonation_ended.

    The guard

    One function in front of every /admin route, in this order:

    1. No session, or the session is one as a customer: 404.
    2. The user is not in staff: 404.
    3. The session is older than 12 hours: send to sign-in, then back.
    4. The route names a role the staff member lacks: 403.

    Answer 404 with the same page the app gives for any unknown address.

    A session as a customer

    • It is a session of its own kind, with its own cookie name and a random token stored as a hash. It does not reuse or copy the customer's session.
    • The app's guard, when it finds this cookie, loads the customer as the current user and also sets "acting staff member" on the request.
    • Routes are marked sensitive in one list. The app's guard answers 403 for them whenever "acting staff member" is set.
    • The cookie lasts as long as the impersonation_minutes input says, and the server checks expires_at on every request as well.
    • Stopping sets ended_at, clears the cookie and returns staff to the customer's page in the console.

    Masking

    ValueShown as
    sam@example.coms•••@example.com
    a@example.com•@example.com
    A phone numberIts last 2 digits, the rest as •
    A nameAs it is

    The whole value is sent to the browser only in answer to "Show", never hidden in the page.

    Suspension

    Check suspended_at where sessions are loaded, so a suspension takes effect on the next request without having to find and end each session.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.

    Named here

    • support may suspend, end sessions and resend a confirmation. Lifting a suspension, revealing a hidden value and changing staff are for admin.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `staff` | `user_id` (primary key), `role`, `added_by`, `added_at` |
    | `staff_records` | `id`, `staff_id`, `kind`, `account_id`, `detail` (JSON), `reason`, `ip`, `at` |
    | `impersonations` | `id`, `staff_id`, `account_id`, `token_hash` (unique), `reason`, `started_at`, `expires_at`, `ended_at` (only if `impersonation` is on) |
    
    `users` gains `suspended_at`. `kind` is one of `action`, `reveal`,
    `impersonation_started` and `impersonation_ended`.
    
    ## The guard
    
    One function in front of every `/admin` route, in this order:
    
    1. No session, or the session is one as a customer: 404.
    2. The user is not in `staff`: 404.
    3. The session is older than 12 hours: send to sign-in, then back.
    4. The route names a role the staff member lacks: 403.
    
    Answer 404 with the same page the app gives for any unknown address.
    
    ## A session as a customer
    
    - It is a session of its own kind, with its own cookie name and a random token
      stored as a hash. It does not reuse or copy the customer's session.
    - The app's guard, when it finds this cookie, loads the customer as the current
      user and also sets "acting staff member" on the request.
    - Routes are marked sensitive in one list. The app's guard answers 403 for them
      whenever "acting staff member" is set.
    - The cookie lasts as long as the `impersonation_minutes` input says, and the
      server checks `expires_at` on every request as well.
    - Stopping sets `ended_at`, clears the cookie and returns staff to the
      customer's page in the console.
    
    ## Masking
    
    | Value | Shown as |
    | --- | --- |
    | `sam@example.com` | `s•••@example.com` |
    | `a@example.com` | `•@example.com` |
    | A phone number | Its last 2 digits, the rest as `•` |
    | A name | As it is |
    
    The whole value is sent to the browser only in answer to "Show", never hidden in
    the page.
    
    ## Suspension
    
    Check `suspended_at` where sessions are loaded, so a suspension takes effect on
    the next request without having to find and end each session.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    
    ## Named here
    
    - `support` may suspend, end sessions and resend a confirmation. Lifting a
      suspension, revealing a hidden value and changing staff are for `admin`.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Read the app. Find how sessions are loaded and where routes are declared. If there is no app yet, build the smallest one: users, sign-in, one page. Check: a test signs a user in the existing way.
    2. Staff and the guard (R1, R2). The tables in design.md, the command that makes the first admin, and the route test. Check: the R1 and R2 acceptance tests pass.
    3. Records (R7). Before anything that needs recording. Check: a record can be written and none can be changed.
    4. Find and show (R3, R4). With masking. Check: the R3 and R4 acceptance tests pass.
    5. Actions (R5). Honour require_reason. Check: the R5 acceptance tests pass.
    6. Sign in as a customer (R6). Only if impersonation is on. Use the impersonation_minutes input and a clock that tests can set. Check: the R6 acceptance tests pass.
    7. Pages (R8). Check: every page can be used with a keyboard alone and at 360 pixels wide.
    8. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Read the app.** Find how sessions are loaded and where routes are declared.
       If there is no app yet, build the smallest one: users, sign-in, one page.
       Check: a test signs a user in the existing way.
    
    2. **Staff and the guard (R1, R2).** The tables in `design.md`, the command that
       makes the first `admin`, and the route test.
       Check: the R1 and R2 acceptance tests pass.
    
    3. **Records (R7).** Before anything that needs recording.
       Check: a record can be written and none can be changed.
    
    4. **Find and show (R3, R4).** With masking.
       Check: the R3 and R4 acceptance tests pass.
    
    5. **Actions (R5).** Honour `require_reason`.
       Check: the R5 acceptance tests pass.
    
    6. **Sign in as a customer (R6).** Only if `impersonation` is on. Use the
       `impersonation_minutes` input and a clock that tests can set.
       Check: the R6 acceptance tests pass.
    
    7. **Pages (R8).**
       Check: every page can be used with a keyboard alone and at 360 pixels wide.
    
    8. **Finish.** Write the README and run the whole test suite.
       Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Agent permissions
shell, network
Secrets it reads
DATABASE_URL

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/admin-console.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.