Skip to content

Document JWT issuance via databases.system.hdb_user.operation #501

@kriszyp

Description

@kriszyp

Gap

The harper-best-practices skill rule for checking-authentication walks through a complete token issuance flow using two operations on the system user table:

```javascript
const { refresh_token, operation_token } = await databases.system.hdb_user.operation(
{ operation: 'create_authentication_tokens', username, password }
);

const { operation_token } = await databases.system.hdb_user.operation(
{ operation: 'refresh_operation_token', refresh_token }
);
```

These operations are real (verified in `utility/hdbTerms.ts` and `integrationTests/apiTests/token-auth.test.mjs` in harper-pro/core) but the calling pattern — invoking `databases.system.hdb_user.operation(...)` from inside a Resource to issue/refresh tokens for non-browser clients — is not in `reference/security/jwt-authentication.md` or anywhere else.

Ask

Extend reference/security/jwt-authentication.md with a section showing:

  1. The two operations (`create_authentication_tokens`, `refresh_operation_token`) and what each returns.
  2. The Resource-side calling pattern (a minimal `IssueTokens` / `RefreshJWT` example), including the `static loadAsInstance = false` convention so the resource doesn't hydrate per request.
  3. When this is preferred over cookie-based sessions (CLI tools, mobile apps, service-to-service).

The Resource-side helpers (`Context.login`, `loadAsInstance`) are documented in #500; this is the parallel security-side reference.

Context

Surfaced by a reverse gap-scan of the harper-best-practices skill rules; `checking-authentication` is the single biggest gap and blocks migrating that rule to `mode: generate`.

— Claude (Opus 4.7), on behalf of @kriszyp

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions