auth/api_token_queries.ts

API token query functions for token CRUD and validation.

Declarations
#

7 declarations

view source

ApiTokenQueryDeps
#

query_api_token_enforce_limit
#

auth/api_token_queries.ts view source

(deps: QueryDeps, account_id: string, max_tokens: number): Promise<number>

Enforce a per-account token limit by evicting the oldest tokens.

Race safety: this function must run inside a transaction alongside the INSERT that created the new token. The caller (POST /tokens/create) uses the default transaction: true (framework-managed transaction wrapping in apply_route_specs), ensuring the INSERT + enforce_limit pair is atomic — concurrent token creation cannot interleave.

deps

query dependencies (must be transaction-scoped)

type QueryDeps

account_id

the account to enforce the limit for

type string

max_tokens

maximum number of tokens to keep

type number

returns

Promise<number>

the number of tokens evicted

query_api_token_list_for_account
#

auth/api_token_queries.ts view source

(deps: QueryDeps, account_id: string): Promise<Omit<ApiToken, "token_hash">[]>

List all tokens for an account (does not include hashes).

Columns are enumerated explicitly to exclude token_hash. Must be updated if the api_token table gains new columns.

deps

type QueryDeps

account_id

type string

returns

Promise<Omit<ApiToken, "token_hash">[]>

query_create_api_token
#

auth/api_token_queries.ts view source

(deps: QueryDeps, id: string, account_id: string, name: string, token_hash: string, expires_at?: Date | null | undefined): Promise<ApiToken>

Store a new API token (the hash, not the raw token).

deps

query dependencies

type QueryDeps

id

the public token id (e.g. tok_abc123)

type string

account_id

the owning account

type string

name

human-readable name

type string

token_hash

blake3 hash of the raw token

type string

expires_at?

optional expiration

type Date | null | undefined
optional

returns

Promise<ApiToken>

the stored token record

query_revoke_all_api_tokens_for_account
#

auth/api_token_queries.ts view source

(deps: QueryDeps, account_id: string): Promise<number>

Revoke all tokens for an account.

deps

query dependencies

type QueryDeps

account_id

the account whose tokens to revoke

type string

returns

Promise<number>

the number of tokens revoked

query_revoke_api_token_for_account
#

auth/api_token_queries.ts view source

(deps: QueryDeps, id: string, account_id: string): Promise<boolean>

Revoke a token only if it belongs to the specified account.

Prevents cross-account token revocation.

deps

query dependencies

type QueryDeps

id

the public token id

type string

account_id

the account that must own the token

type string

returns

Promise<boolean>

true if a token was revoked, false if not found or wrong account

query_validate_api_token
#

auth/api_token_queries.ts view source

(deps: ApiTokenQueryDeps, raw_token: string, ip: string | undefined, pending_effects: Promise<void>[] | undefined): Promise<ApiToken | undefined>

Validate a raw API token and return the token record.

Hashes the token with blake3, looks up the hash, and checks expiration. Updates last_used_at and last_used_ip on success (fire-and-forget — errors logged, never thrown).

deps

query dependencies with logger

type ApiTokenQueryDeps

raw_token

the raw API token from the Authorization header

type string

ip

the client IP address (for audit)

type string | undefined

pending_effects

optional array to register the usage-tracking effect for later awaiting

type Promise<void>[] | undefined

returns

Promise<ApiToken | undefined>

the token record if valid, or undefined

Depends on
#

Imported by
#