export type TokenRole = 'admin' | 'user';
export interface TokenRow {
    id: string;
    label: string;
    /** sha256 hex of the raw token string. */
    hash: string;
    created_at: number;
    last_used_at: number | null;
    /** Granted role. Optional on disk for back-compat with pre-R12 token
     *  files — readers MUST treat missing field as 'admin' since that was
     *  the implicit behaviour before role gating landed. New tokens
     *  default to 'admin' too (operator-friendly); the operator can
     *  explicitly demote by passing `role: 'user'` to createToken or via
     *  the PATCH /api/tokens/:id endpoint. */
    role?: TokenRole;
}
/** Raw token format: `agim_` + 40 hex chars. Easy to identify in logs. */
export declare function generateRawToken(): string;
/** Create + persist a new token. Returns the raw value (caller must
 *  surface it to the operator immediately — it is NOT recoverable later). */
export declare function createToken(label: string, opts?: {
    actor?: string;
    traceId?: string;
    role?: TokenRole;
}): {
    id: string;
    raw: string;
    createdAt: number;
    role: TokenRole;
};
/** List tokens with secrets stripped. */
export declare function listTokens(): Array<Omit<TokenRow, 'hash'>>;
/** Resolve the role of a token by id. Missing field reads as 'admin'
 *  for back-compat with pre-R12 tokens.json files. */
export declare function getTokenRole(id: string): TokenRole;
/** Convenience: true iff the token's role is 'admin'. */
export declare function isAdminTokenId(id: string): boolean;
/** Demote / promote an existing token. Returns true on change. */
export declare function setTokenRole(id: string, role: TokenRole, opts?: {
    actor?: string;
    traceId?: string;
}): boolean;
/** Revoke (delete) a token by id. Returns true if a row was removed. */
export declare function revokeToken(id: string, opts?: {
    actor?: string;
    traceId?: string;
}): boolean;
/**
 * Verify a raw token. Updates `last_used_at` on success. Returns the
 * matching row id, or null if no match. Uses timing-safe comparison on
 * the sha256 digest.
 */
export declare function verifyToken(raw: string): string | null;
/** True when at least one token is registered. */
export declare function hasAnyToken(): boolean;
/** Consume the in-memory bootstrap-token holder. Intended for interactive
 *  CLI flows that need the raw value once and then drop it. Returns null
 *  after the first call or when no bootstrap happened. */
export declare function consumeBootstrapTokenRaw(): {
    raw: string;
    id: string;
} | null;
/** Retrieve the one-time bootstrap raw token (memory holder first, then file). */
export declare function retrieveWebBootstrapTokenRaw(): {
    raw: string;
    id: string;
} | null;
/**
 * First-launch helper. If no token exists and AGIM_WEB_AUTH !== 'off',
 * create a bootstrap token. Idempotent — does nothing if any token
 * already exists. Returns the raw value when generated, null otherwise.
 *
 * Compliance note (R13 A3): the raw token value is NEVER written to
 * stdout or pino — both go to journald in systemd deployments where any
 * `journalctl -u agim` reader could harvest the token before the
 * operator consumes it. Instead we:
 *
 *   - write the raw once to WEB_BOOTSTRAP_TOKEN_FILE (chmod 600)
 *   - print a banner pointing at `agim token bootstrap` / `cat` that file
 *   - emit a structured log with the id only (no raw)
 *
 * The raw is still returned from this function (callers like the
 * interactive setup may print it directly to their TTY), so existing
 * behaviour for non-systemd installs is preserved.
 */
export declare function bootstrapIfEmpty(): string | null;
/** True iff token auth is enabled (env opt-out turned off). */
export declare function isAuthEnabled(): boolean;
/** Path to the tokens file (for diagnostics / external tools). Re-resolves
 *  AGIM_HOME on each call so tests / runtime env overrides apply. */
export declare function getTokensFilePath(): string;
/** Path to the one-time web bootstrap token file. Re-resolves AGIM_HOME
 *  on each call. */
export declare function getWebBootstrapTokenFile(): string;
/** Test helper: reset the in-memory bootstrap-token holder so a fresh
 *  test starts with a clean slate. NOT for production use. */
export declare function __resetBootstrapHolderForTesting(): void;
//# sourceMappingURL=access-token.d.ts.map