@rebasepro/server 0.23.0 → 0.24.1-canary.g56af4a4

package/dist/auth/access.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The access model this backend serves, and the one gate every scope check
+ * goes through.
+ *
+ * The model — the app's declared roles and scopes beside the built-in ones —
+ * comes from the users collection's `auth` block and is configured once at
+ * boot, like the JWT keys. A process serves one backend's auth, so one model.
+ *
+ * Who holds what:
+ *
+ * - A credential that narrows its person — an API key, an MCP token — puts
+ *   its scopes in the request context (`c.set("scopes", …)`) when it is
+ *   verified. That list is the whole answer for it.
+ * - Anyone else is a person (or the service key, which is the `admin` role),
+ *   and holds what their roles hold: `scopesForRoles`.
+ *
+ * @module
+ */
+import type { Context, MiddlewareHandler } from "hono";
+import { type AccessModel, type CollectionConfig } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import { ApiError } from "../api/errors.js";
+import type { AuthRepository } from "./interfaces.js";
+/** The account a personal key acts as, as it is now. Null when it no longer exists. */
+export type KeyOwnerResolver = (uid: string) => Promise<{
+    roles: string[];
+} | null>;
+/**
+ * How a personal key finds its owner in an account store: the account as it
+ * is now — a missing or disabled one is no owner — and its roles.
+ *
+ * One read where the store answers both at once: `getAccountAccessState`, the
+ * statement every access token is already judged against, which reads roles
+ * and `disabled_at` together. Otherwise the account, then its roles — the two
+ * reads this always made, one round trip more per request.
+ */
+export declare function keyOwnerResolverFor(repo: Pick<AuthRepository, "getUserById" | "getUserRoleIds" | "getAccountAccessState">): KeyOwnerResolver;
+/** The access model the running backend serves. Built-ins only until boot configures it. */
+export declare function getAccessModel(): AccessModel;
+/**
+ * How a personal key finds its owner, or undefined when personal keys are
+ * off — in which case every personal key, however valid, is refused.
+ */
+export declare function getKeyOwnerResolver(): KeyOwnerResolver | undefined;
+/**
+ * Install the access model, and — when the app enables `auth.personalKeys`
+ * and has an account store to read owners from — how personal keys find
+ * their owner. Called once by `initializeRebaseBackend`.
+ */
+export declare function configureAccess(options: {
+    model: AccessModel;
+    resolveKeyOwner?: KeyOwnerResolver;
+}): void;
+/** A declaration the access model cannot be built from. Fails the boot. */
+export declare class AccessModelError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build the access model from the users collection's `auth` block, refusing
+ * anything that would read as a grant it is not.
+ *
+ * - `admin` may not be declared: it is built in and holds everything, and a
+ *   declaration would either repeat that or quietly narrow it.
+ * - An app scope may not reuse a built-in resource name (`logs:export`): the
+ *   built-in resources are Rebase's, and a reader of `logs:*` should not have
+ *   to know which half is whose.
+ * - A role may not list a data-plane scope: a person's data access is the
+ *   collection's `securityRules`, so `data:write` on a role would grant nothing
+ *   and look like it granted something.
+ */
+export declare function accessModelFromCollections(collections: readonly CollectionConfig[]): AccessModel;
+/**
+ * Everything the caller of this request may do. Empty for a request with no
+ * caller.
+ */
+export declare function callerScopes(c: Context<HonoEnv>): string[];
+/**
+ * Whether this request's caller holds the `admin` role. The service key signs
+ * in as one.
+ */
+export declare function callerIsAdmin(c: Context<HonoEnv>): boolean;
+/** Does this request's caller hold `scope`, on `target` when one is given? */
+export declare function hasScope(c: Context<HonoEnv>, scope: string, target?: string): boolean;
+/**
+ * The refusal for a missing scope, worded for whoever is holding the
+ * credential. `details.requiredScope` names it for clients that branch.
+ */
+export declare function scopeMissing(c: Context<HonoEnv>, scope: string, target?: string): ApiError;
+/**
+ * Refuse a request whose caller does not hold `scope`.
+ *
+ * `target` narrows the check to one collection, bucket, function or app
+ * resource, and may be read from the request. Mount after authentication: a
+ * request with no caller is refused as unauthenticated, not as unscoped.
+ *
+ * @example
+ * ```ts
+ * app.post("/deploy/:project", requireScope("project:deploy", c => c.req.param("project")), handler);
+ * ```
+ */
+export declare function requireScope(scope: string, target?: string | ((c: Context<HonoEnv>) => string | undefined)): MiddlewareHandler<HonoEnv>;
+/**
+ * Refuse a request unless its caller holds the scope for its HTTP method:
+ * `read` for GET and HEAD, `write` for everything else. For an admin surface
+ * whose reads and writes split exactly along the method.
+ */
+export declare function requireScopeByMethod(scopes: {
+    read: string;
+    write: string;
+}): MiddlewareHandler<HonoEnv>;
+/**
+ * Refuse to let the caller act on an account — edit it, reset its password,
+ * delete it — when that account holds anything the caller does not.
+ *
+ * `users:write` is the scope that lets a support role manage accounts, and
+ * without this it would also let that role reset an administrator's password
+ * and sign in as them.
+ */
+export declare function assertMayManageAccount(c: Context<HonoEnv>, targetRoles: readonly string[]): void;
+/** Refuse to let the caller grant roles that hold anything the caller does not. */
+export declare function assertMayGrantRoles(c: Context<HonoEnv>, roles: readonly string[]): void;

package/dist/auth/adapter-middleware.d.ts

@@ -11,7 +11,8 @@
  * 3. Scopes the DataDriver via `withAuth()` for RLS
  * 4. Rejects a presented-but-unverifiable token with 401, whatever
  *    `requireAuth` says
- * 5. Enforces auth (401) when `requireAuth` is true and no user is found
+ * 5. Honours or refuses `x-rebase-impersonate` (`applyImpersonation`)
+ * 6. Enforces auth (401) when `requireAuth` is true and no user is found
  *
  * The behavior is identical to `createAuthMiddleware()` — only the
  * token verification strategy is pluggable.

package/dist/auth/address-ownership.d.ts

@@ -50,4 +50,19 @@ export declare function identityVouchesForAddress(identity: UserIdentityData, em
  * on it is the takeover itself, and leaving the account unverified while
  * signing the owner in would share the account all the same.
  */
-export declare function confirmAddressOwnership(authRepo: AuthRepository, user: Pick<UserData, "id" | "email" | "passwordHash">, passwordHash: string | null): Promise<void>;
+export declare function confirmAddressOwnership(authRepo: AuthRepository, user: Pick<UserData, "id" | "email" | "passwordHash">, passwordHash: string | null, options?: {
+    /**
+     * Whoever proved the address also holds a live session of this very
+     * account, so nothing on it is a stranger's: it was all put there by
+     * the person now holding the inbox. Nothing is removed and no session
+     * ends; the account is only marked verified. See `GET /auth/verify-email`.
+     */
+    everythingProven?: boolean;
+}): Promise<AddressProofOutcome>;
+/** What a first proof of address took off the account. */
+export interface AddressProofOutcome {
+    /** A password was on the account, nobody proved it, and it is gone. */
+    removedPassword: boolean;
+    /** The providers whose identities were detached for not vouching for the address. */
+    removedProviders: string[];
+}

package/dist/auth/admin-roles-route.d.ts

@@ -1,7 +1,9 @@
 /**
- * Admin endpoint for listing all roles.
+ * Admin endpoint for listing roles.
  *
- * Mounts: GET /roles
+ * Mounts: GET /roles — the built-in `admin` role and the roles the app
+ * declares under `auth.roles` on the users collection, with the scopes each
+ * holds. Requires `users:read`.
  */
 import { Hono } from "hono";
 import type { AuthRepository } from "./interfaces.js";

package/dist/auth/admin-roles.d.ts

@@ -1,24 +1,21 @@
 /**
- * Which role names carry administrative privilege.
+ * The admin role and scope matching, for code that may not import
+ * `@rebasepro/types`.
  *
- * One definition, because there used to be several and they disagreed.
- * `requireAdmin` accepted `admin` **or** `schema-admin`; the guard that refuses
- * a dangerous `defaultRole` compared against `admin` alone. So
- * `AUTH_DEFAULT_ROLE=schema-admin` passed the guard and made every public
- * registrant an administrator — and, since a `schema-admin` may edit users, one
- * of them could then grant themselves real `admin` and keep it.
+ * The custom-functions surface (`@rebasepro/server/functions`) must bundle for
+ * a runtime with no Node built-ins and imports nothing but `hono`, so its
+ * guards cannot reach the canonical definitions in `@rebasepro/types`
+ * (`ADMIN_ROLE`, `hasAdminRole`, `scopeGrants`). These are the same rules,
+ * restated, and `test/admin-roles.test.ts` holds them equal.
  *
- * The guard and the check have to read the same list or the gap comes back, so
- * neither of them owns it.
- *
- * `schema-admin` is here deliberately: it can reach the schema editor and the
- * SQL surfaces, which is administrative by any definition that matters. If a
- * genuinely lesser role is added later, it does not belong in this list — it
- * belongs in a capability check of its own.
+ * Everything else imports the `@rebasepro/types` versions.
+ */
+/** The one built-in role. It holds every scope. */
+export declare const ADMIN_ROLE_NAME = "admin";
+/** Does this list of roles include the admin role? */
+export declare function holdsAdminRole(roles: readonly string[] | null | undefined): boolean;
+/**
+ * Does a set of held scopes grant `scope`, optionally on one `target`? The
+ * unqualified grant covers every target; `scope:target` covers its own.
  */
-export declare const ADMINISTRATIVE_ROLES: readonly ["admin", "schema-admin"];
-export type AdministrativeRole = (typeof ADMINISTRATIVE_ROLES)[number];
-/** Does this single role name carry administrative privilege? */
-export declare function isAdministrativeRole(role: string): role is AdministrativeRole;
-/** Does any role in this list carry administrative privilege? */
-export declare function hasAdministrativeRole(roles: readonly string[] | null | undefined): boolean;
+export declare function heldScopesGrant(held: readonly string[], scope: string, target?: string): boolean;

package/dist/auth/admin-user-ops.d.ts

@@ -14,7 +14,7 @@
 import type { AuthRepository } from "./interfaces.js";
 import type { EmailService, EmailConfig } from "../email/index.js";
 import type { ResolvedAuthHooks } from "./auth-hooks.js";
-import type { AuthAdapter, AuthCollectionConfig, UserCreationFinalizeResult, UserCreationPrepareResult } from "@rebasepro/types";
+import type { AuthAdapter, AuthCollectionConfig, UserCreationFinalizeResult, UserCreationOptions, UserCreationPrepareResult } from "@rebasepro/types";
 /**
  * Generate a cryptographically secure random password that meets strength requirements.
  *
@@ -54,6 +54,25 @@ export interface AdminUserPrepareResult {
     /** Whether an invitation was sent (only relevant when hookHandledEmail is true). */
     invitationSent: boolean;
 }
+/**
+ * The body field with which an administrator waives the password policy for
+ * one create — an import of accounts whose passwords another system chose.
+ * An instruction to the door, never data: it reaches neither the row nor a
+ * create hook.
+ */
+export declare const SKIP_PASSWORD_POLICY_FIELD = "skipPasswordPolicy";
+/**
+ * Hold a create body's chosen `password` to the password policy, as
+ * registration and every other door that sets a password are, and return the
+ * body without {@link SKIP_PASSWORD_POLICY_FIELD}.
+ *
+ * The flag waives the policy only when the door says the caller may waive it
+ * (`options.mayWaivePasswordPolicy`, an administrator); from anyone else it
+ * waives nothing, and a refusal says so.
+ *
+ * @throws ApiError 400 `WEAK_PASSWORD`
+ */
+export declare function enforceCreationPasswordPolicy(body: Record<string, unknown>, resolvedHooks: Pick<ResolvedAuthHooks, "validatePasswordStrength">, options?: UserCreationOptions): Record<string, unknown>;
 /**
  * Prepare user values for an admin-initiated user creation.
  *
@@ -62,9 +81,12 @@ export interface AdminUserPrepareResult {
  * 2. Backend-level `AuthHooks.onAdminCreateUser` — global override
  * 3. Built-in default — generate password → hash → normalize email
  *
+ * Before any of them, a chosen password is held to the password policy
+ * ({@link enforceCreationPasswordPolicy}).
+ *
  * The caller is responsible for persisting (via `driver.save()`).
  */
-export declare function prepareAdminUserValues(body: Record<string, unknown>, ctx: AdminUserContext): Promise<AdminUserPrepareResult>;
+export declare function prepareAdminUserValues(rawBody: Record<string, unknown>, ctx: AdminUserContext, options?: UserCreationOptions): Promise<AdminUserPrepareResult>;
 /**
  * Handle post-creation work for admin-created users.
  *

package/dist/auth/admin-users-route.d.ts

@@ -3,10 +3,12 @@
  *
  * Mounts:
  *   GET /users
+ *   GET /users/pick
  *   GET /users/:uid
  *   POST /users
  *   PUT /users/:uid
  *   DELETE /users/:uid
+ *   DELETE /users/:uid/mfa
  *   POST /bootstrap
  */
 import { Hono } from "hono";

package/dist/auth/api-keys/api-key-middleware.d.ts

@@ -1,34 +1,48 @@
 /**
- * Hono middleware for authenticating requests via Service API Keys.
+ * Authenticating requests that present an API key (`rk_`).
  *
- * This middleware is integrated into `createAuthMiddleware()` and
- * activates only when the bearer token starts with `rk_`. It:
+ * {@link resolveApiKey} turns a presented key into the identity it acts as and
+ * the scopes it holds; the HTTP middlewares, the realtime socket and `/mcp`
+ * all call it, so a key means the same thing on every surface.
  *
- * 1. Hashes the token with SHA-256
- * 2. Looks up the hash in the `rebase.api_keys` table
- * 3. Validates the key is not revoked and not expired
- * 4. Sets `c.set("user", ...)` and `c.set("apiKey", ...)` for downstream use
- * 5. Scopes the DataDriver via `withAuth()` using the API key's service identity
+ * - A **service key** acts as `api-key:<id>`, with the RLS roles `service`
+ *   plus whatever it was given, and holds exactly its scopes.
+ * - A **personal key** acts as its owner — their uid and their roles as they
+ *   are *now*, read on every use — and holds its scopes narrowed to what the
+ *   owner's roles still hold. Demote the owner and the key shrinks with them;
+ *   delete the account and the key stops.
  *
- * Authorization is double-gated for API keys: the key's own permission list
- * (checked by the REST generator) is one ceiling, and Postgres RLS is another,
- * independent one — `withAuth()` runs API-key requests as the restricted
- * `rebase_user` role like any other caller. An `admin` key passes RLS via the
- * injected `default_admin` policies; a non-admin key (roles `["service"]`,
- * uid `api-key:<id>`) only sees rows that a policy explicitly grants to the
- * `service` role or to the public. Owner-style policies
- * (`owner_id = rebase.uid()`) never match an API key's synthetic uid.
+ * A key never bypasses RLS: the request's driver is scoped to the identity
+ * like any other caller's, so the scopes are one ceiling and the database's
+ * policies another, independent one.
  *
  * @module
  */
 import type { Context, MiddlewareHandler } from "hono";
-import type { DataDriver } from "@rebasepro/types";
+import { type DataDriver } from "@rebasepro/types";
 import type { HonoEnv } from "../../api/types.js";
 import type { ApiKeyStore } from "./api-key-store.js";
+import type { ApiKeyMasked } from "./api-key-types.js";
 /**
  * Check whether a token looks like a Rebase API key.
  */
 export declare function isApiKeyToken(token: string): boolean;
+/** Who a verified key acts as, and what it may do. */
+export interface ApiKeyIdentity {
+    uid: string;
+    roles: string[];
+    scopes: string[];
+    apiKey: ApiKeyMasked;
+}
+/** A presented key that does not authenticate, and why. */
+export interface ApiKeyRefusal {
+    message: string;
+}
+/**
+ * Verify a presented key: it exists, is live, and — for a personal key —
+ * personal keys are on and its owner still exists. Records the use.
+ */
+export declare function resolveApiKey(store: ApiKeyStore, token: string): Promise<ApiKeyIdentity | ApiKeyRefusal>;
 /**
  * Options for the API key authentication handler.
  */
@@ -37,59 +51,46 @@ export interface ApiKeyAuthOptions {
     driver: DataDriver;
 }
 /**
- * Validate an API key token and populate the Hono context.
- *
- * Returns `true` if the key is valid and context has been populated,
- * or returns an error Response if the key is invalid.
+ * Validate an API key token and populate the Hono context: `user`, `apiKey`,
+ * `scopes` and the RLS-scoped `driver`.
  *
- * This is NOT a standalone middleware — it's called from within
- * `createAuthMiddleware()` when a `rk_` prefixed token is detected.
+ * Returns `true` when the context is populated, or the error Response.
  */
 export declare function validateApiKey(c: Context<HonoEnv>, token: string, options: ApiKeyAuthOptions): Promise<Response | true>;
 /**
- * Permission guard for API-key requests to the storage router.
- *
- * Storage previously did not accept API keys at all (`rk_` tokens were
- * misparsed as JWTs and 401'd). Now that the pre-auth middleware
- * authenticates them, this guard decides what they may do: the key needs a
- * `"storage"` permission entry (or the global `"*"` wildcard) covering the
- * operation derived from the HTTP method. Requests not authenticated via an
- * API key pass through to the storage router's own auth gates.
- *
- * TUS resumable-upload routes (`/tus`, `/tus/:id`) are classified as `write`
- * for EVERY method: the protocol's offset check is a GET and its cancel is a
- * DELETE, but both are steps of an upload — a write-scoped key must be able
- * to complete (and abort) its own resumable upload without also holding
- * `read`/`delete` on stored objects.
+ * The 403 for a credential that lacks a data-plane scope outside the REST
+ * generator (storage and functions). Names the scope that would grant it.
  */
-export declare function createStorageApiKeyGuard(): MiddlewareHandler<HonoEnv>;
+export declare function forbidScope(c: Context<HonoEnv>, scope: string, target?: string): Response;
 /**
- * Permission guard for API-key requests to the custom-functions router.
+ * Scope guard for the resumable-upload routes (`/tus/:id`).
  *
- * The collection permission guard lives in the REST generator and never sees
- * function routes, so before this middleware existed ANY valid API key —
- * however narrowly scoped — could invoke every custom function. This guard
- * closes that: API-key requests must hold a `"functions"`/`"functions/<name>"`
- * permission entry (or the global `"*"` wildcard) for the derived operation.
+ * Every step of an upload — the offset check (HEAD), the chunks (PATCH), the
+ * cancel (DELETE) — is part of writing it, so all of them need
+ * `storage:write`. Which source the upload writes to was checked when it was
+ * created; these steps only reach an upload the same caller owns.
+ */
+export declare function createTusScopeGuard(): MiddlewareHandler<HonoEnv>;
+/**
+ * Scope guard for the custom-functions router: a narrowed credential needs
+ * `functions:invoke` on the function it calls. The functions index — the
+ * listing at the mount point itself — needs the unqualified scope.
  *
- * Non-API-key requests (JWT, service key, anonymous) pass through untouched —
- * functions decide their own auth for those, as before.
+ * People pass: what a person may do inside a function is the function's own
+ * business, as it always was.
  *
  * @param mountPrefix - The path the functions router is mounted at
  *                      (e.g. `/api/functions`), used to extract the function
  *                      name from the request path.
  */
-export declare function createFunctionApiKeyGuard(mountPrefix: string): MiddlewareHandler<HonoEnv>;
+export declare function createFunctionScopeGuard(mountPrefix: string): MiddlewareHandler<HonoEnv>;
 /**
- * Standalone pre-auth middleware for `rk_` bearer tokens.
+ * Pre-auth middleware for `rk_` bearer tokens.
  *
- * Routers whose auth gate is JWT-based (`requireAuth` / `createRequireAuth` —
- * the admin surfaces: admin users/roles, api-keys management, cron, backups,
- * logs, schema editor) don't know about API keys. Mounting this middleware in
- * front of them authenticates `rk_` tokens and populates the request context;
- * the downstream gates then see the already-resolved user and apply their
- * role checks (`requireAdmin`) as usual — so an `admin: true` key passes and
- * a non-admin key is rejected with 403.
+ * Routers whose auth gate is JWT-based (`createRequireAuth` — the admin
+ * surfaces, the key routes) don't know about API keys. Mounted in front of
+ * them, this authenticates `rk_` tokens and populates the request context; the
+ * downstream gates then see the already-resolved caller and check its scopes.
  *
  * Requests without an `rk_` bearer token pass through untouched. An invalid,
  * revoked, or expired `rk_` token is rejected here (401) rather than falling

package/dist/auth/api-keys/api-key-routes.d.ts

@@ -1,32 +1,62 @@
 /**
- * Admin routes for managing Service API Keys.
+ * Routes for managing API keys.
  *
- * Mounted under `/api/admin/api-keys` with `requireAuth` + `requireAdmin`.
- * All routes return masked keys (never the hash). The full plaintext key
- * is returned exactly once in the POST response.
+ * - {@link createApiKeyRoutes} — the project's service keys, under
+ *   `/api/admin/api-keys`, for holders of `keys:read` / `keys:write`.
+ * - {@link createPersonalKeyRoutes} — the caller's own personal keys, under
+ *   `/api/auth/keys`, when the app enables `auth.personalKeys`.
+ *
+ * All routes return masked keys (never the hash). The full plaintext key is
+ * returned exactly once, in the response that creates it. No API key may call
+ * either router.
  *
  * @module
  */
 import { Hono } from "hono";
+import type { AccessModel } from "@rebasepro/types";
 import type { HonoEnv } from "../../api/types.js";
 import type { ApiKeyStore } from "./api-key-store.js";
+import { type KeyTargets } from "./key-grant.js";
 export interface ApiKeyRouteOptions {
     store: ApiKeyStore;
     serviceKey?: string;
     /**
      * Read the caller's roles from the database rather than from their token.
      *
-     * Without it this router trusted the `roles` claim, and a key minted here
-     * never expires and may carry `admin: true` — so an administrator demoted
-     * an hour ago could still mint themselves permanent admin access, and the
-     * demotion would not take effect until a token nobody can see had run out.
-     * See `createRequireAuth`.
+     * A key minted here may outlive the session that minted it, so the roles
+     * that bound what it may hold must be the caller's roles now — not the
+     * ones a token issued before a demotion still claims. See
+     * `createRequireAuth`.
      */
     resolveRoles?: (uid: string) => Promise<string[]>;
     /** Repository for the token-revocation watermark. See `createRequireAuth`. */
-    revocationRepo?: Pick<import("../interfaces.js").AuthRepository, "getTokensValidAfter">;
+    revocationRepo?: import("../token-revocation.js").AccessJudgeRepository;
+    /** What a scope's target may name. Unset, targets are not checked for existence. */
+    targets?: KeyTargets;
+    /** The access model to validate scopes against. Defaults to the configured one. */
+    accessModel?: () => AccessModel;
 }
 /**
- * Create admin routes for API key management.
+ * The project's service keys: `GET` needs `keys:read`, everything else
+ * `keys:write`.
  */
 export declare function createApiKeyRoutes(options: ApiKeyRouteOptions): Hono<HonoEnv>;
+export interface PersonalKeyRouteOptions {
+    store: ApiKeyStore;
+    /** Whether the app enabled `auth.personalKeys`. Off, every route explains how to turn it on. */
+    enabled: boolean;
+    /** Recognised only to be refused with a reason: the service key has no account. */
+    serviceKey?: string;
+    resolveRoles?: (uid: string) => Promise<string[]>;
+    revocationRepo?: import("../token-revocation.js").AccessJudgeRepository;
+    targets?: KeyTargets;
+    accessModel?: () => AccessModel;
+}
+/**
+ * The caller's own keys. Each acts as the caller — their account, their roles
+ * as they are when the key is used — and holds no scope the caller does not.
+ *
+ * For a signed-in account only: not a key, not the service key (it has no
+ * account to act as) and not a guest, whose account is one sign-out from gone.
+ */
+export declare function createPersonalKeyRoutes(options: PersonalKeyRouteOptions): Hono<HonoEnv>;

package/dist/auth/api-keys/api-key-store.d.ts

@@ -1,5 +1,5 @@
 /**
- * Database operations for Service API Keys.
+ * Database operations for API keys.
  *
  * Uses the DataDriver's `admin.executeSql` capability (same pattern as
  * the cron-store and ensure-tables modules). All data lives in the
@@ -8,22 +8,45 @@
  * @module
  */
 import type { DataDriver } from "@rebasepro/types";
-import type { ApiKey, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "./api-key-types.js";
+import type { ApiKey, ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, UpdateApiKeyRequest } from "./api-key-types.js";
+/** What a new key row is made of, already validated by the route that asked. */
+export interface NewApiKey {
+    name: string;
+    kind: ApiKeyKind;
+    scopes: string[];
+    /** RLS roles beside `service`. Always empty for a personal key. */
+    roles: string[];
+    /** The account a personal key acts as. */
+    owner_uid: string | null;
+    rate_limit: number | null;
+    expires_at: string | null;
+}
+/** Which keys a listing returns. */
+export type ApiKeyFilter = {
+    kind: "service";
+} | {
+    kind: "personal";
+    owner_uid: string;
+};
 export interface ApiKeyStore {
     /** Ensure the `rebase.api_keys` table exists. Called once on startup. */
     ensureTable(): Promise<void>;
     /** Create a new API key. Returns the full plaintext key exactly once. */
-    createApiKey(request: CreateApiKeyRequest, createdBy: string): Promise<ApiKeyWithSecret>;
+    createApiKey(key: NewApiKey, createdBy: string): Promise<ApiKeyWithSecret>;
     /** Look up an API key by its SHA-256 hash. Returns `null` if not found. */
     findByKeyHash(hash: string): Promise<ApiKey | null>;
-    /** List all API keys (masked, never includes hash). */
-    listApiKeys(): Promise<ApiKeyMasked[]>;
+    /** List keys (masked, never includes hash), newest first. */
+    listApiKeys(filter: ApiKeyFilter): Promise<ApiKeyMasked[]>;
     /** Get a single API key by ID (masked). */
     getApiKeyById(id: string): Promise<ApiKeyMasked | null>;
-    /** Update name, permissions, rate_limit, or expires_at. */
+    /** Update name, scopes, roles, rate_limit, or expires_at. */
     updateApiKey(id: string, updates: UpdateApiKeyRequest): Promise<ApiKeyMasked | null>;
-    /** Soft-delete: set `revoked_at` to now. */
-    revokeApiKey(id: string): Promise<boolean>;
+    /**
+     * Soft-delete: set `revoked_at` to now. With `owner_uid`, only that
+     * account's personal key is revoked — the answer is false for anyone
+     * else's, so a route can 404 without saying whether the id exists.
+     */
+    revokeApiKey(id: string, owner_uid?: string): Promise<boolean>;
     /** Touch `last_used_at` to the current timestamp. */
     updateLastUsed(id: string): Promise<void>;
 }

package/dist/auth/api-keys/api-key-types.d.ts

@@ -1,15 +1,15 @@
 /**
- * Type definitions for Service API Keys.
+ * Type definitions for API keys.
  *
- * The wire contract — permissions, the masked key, the create/update payloads —
- * lives in `@rebasepro/types`, because the client SDK needs the same shapes and
- * the two declarations had already drifted apart. Only {@link ApiKey}, the
- * database row carrying `key_hash`, is server-side and stays here.
+ * The wire contract — scopes, the masked key, the create/update payloads —
+ * lives in `@rebasepro/types`, because the client SDK needs the same shapes.
+ * Only {@link ApiKey}, the database row carrying `key_hash`, is server-side
+ * and stays here.
  *
  * @module
  */
-import type { ApiKeyPermission } from "@rebasepro/types";
-export type { ApiKeyPermission, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
+import type { ApiKeyKind } from "@rebasepro/types";
+export type { ApiKeyKind, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequest, CreatePersonalKeyRequest, UpdateApiKeyRequest } from "@rebasepro/types";
 /**
  * Full database row for an API key.
  * The `key_hash` is never exposed via the API — only stored for lookup.
@@ -17,19 +17,17 @@ export type { ApiKeyPermission, ApiKeyMasked, ApiKeyWithSecret, CreateApiKeyRequ
 export interface ApiKey {
     id: string;
     name: string;
+    kind: ApiKeyKind;
     /** First 12 characters of the plaintext key, for display only. */
     key_prefix: string;
     /** SHA-256 hash of the full plaintext key. */
     key_hash: string;
-    permissions: ApiKeyPermission[];
-    /**
-     * When true, the key is granted the `admin` role: it passes the
-     * admin-gated routes (users, roles, cron, backups, logs, API keys) and
-     * the RLS `default_admin` policies. Non-admin keys carry only the
-     * `service` role — RLS grants them nothing unless a collection policy
-     * explicitly names that role.
-     */
-    admin: boolean;
+    /** `resource:action[:target]` scope strings. */
+    scopes: string[];
+    /** RLS roles a service key runs as, beside `service`. Empty on a personal key. */
+    roles: string[];
+    /** The account a personal key acts as. Null on a service key. */
+    owner_uid: string | null;
     /**
      * Requests per 15-minute window. `null` means "no per-key override" —
      * the data rate limiter then applies its default API-key limit

package/dist/auth/api-keys/http-operation.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which data-plane operation an HTTP request performs, for the scope it needs:
+ * `data:read`, `data:write` or `data:delete` (and the same for storage).
+ *
+ * @module
+ */
+/** The operation part of a data-plane scope. */
+export type DataOperation = "read" | "write" | "delete";
+/**
+ * Map an HTTP method to the operation it performs.
+ *
+ * - `GET`, `HEAD`, `OPTIONS` → `"read"`
+ * - `POST`, `PUT`, `PATCH`  → `"write"`
+ * - `DELETE`                → `"delete"`
+ *
+ * Any other method is a `"write"`: a verb this does not know is not assumed
+ * to be harmless.
+ */
+export declare function httpMethodToOperation(method: string): DataOperation;