Tokens

Documentation from vllnt/convex-tokens, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

@vllnt/convex-tokens

Hashed-secret token primitive with mint-once, TTL, revoke and scope, as a Convex component — mint a secret against an opaque resourceRef, return the raw value once, and store only its SHA-256 hash.

Copy codeconst tokens = new Tokens(components.tokens);
const { token, id } = await tokens.mint(ctx, { resourceRef }); // show `token` once
const result = await tokens.validate(ctx, rawToken); // { valid: true, resourceRef? } | { valid: false }

Features

• Mint-once — the raw token is returned a single time and never persisted; only its digest rests in the component.
• Hash-at-rest — a leaked DB row can't be replayed; digest is SHA-256 by default, SHA-512 configurable, fixed per mount.
• Server-sourced time — expiresAt and validate-time now come from the server clock; expiry can't be spoofed.
• TTL with clamp — every token expires; a requested ttlMs is clamped server-side into [MIN_TTL_MS, maxTtlMs].
• Revoke — invalidate a token before it expires, via a transition contract.
• Scopes — global by default, or namespace per tenant / purpose / locale.
• Self-pruning cron + safe management surface — sweeps expired/stale-revoked tokens; list/getMetadata never return the hash.

Installation

Copy codepnpm add @vllnt/convex-tokens

Peer dependency: convex@^1.41.0.

Usage

Copy code// convex/convex.config.ts
import { defineApp } from "convex/server";
import tokens from "@vllnt/convex-tokens/convex.config";

const app = defineApp();
app.use(tokens);
export default app;

Copy code// convex/api-keys.ts — host owns auth; pass an opaque resourceRef in.
import { components } from "./_generated/api";
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { Tokens } from "@vllnt/convex-tokens";

const tokens = new Tokens(components.tokens);

export const issue = mutation({
  args: { userId: v.string() },
  // returns { token, id }; show `token` to the user once — it is never recoverable.
  handler: (ctx, { userId }) => tokens.mint(ctx, { resourceRef: userId }),
});

export const check = query({
  args: { token: v.string() },
  handler: (ctx, { token }) => tokens.validate(ctx, token),
});

API Reference

Full reference: docs/API.md — including client options (defaultScope, defaultTtlMs, maxTtlMs, hashAlgo, …) and the hash-guard error code.

React

Optional, tree-shakeable front-tooling at @vllnt/convex-tokens/react; react and convex are optional peer deps. No-leak: hooks expose only token metadata — never a raw token or hash. Pass the host's own re-exported list query ref.

Copy codeimport { useTokens } from "@vllnt/convex-tokens/react";
import { api } from "./convex/_generated/api";

const tokens = useTokens(api.apiKeys.list, { resourceRef }); // TokenMetadata[] | undefined

Security

• Auth-agnostic — the host resolves identity and passes an opaque resourceRef; the component never authenticates.
• Hash-at-rest — the raw token is hashed client-side (Web Crypto, SHA-256 by default); only the digest is stored, so a compromised DB yields no usable token.
• Time is server-sourced (expiry can't be forged), validate returns a discriminated union, and the management surface (list, getMetadata) never returns the hash.

See docs/API.md.

Testing

Copy codepnpm test           # single run
pnpm test:coverage  # enforced 100% on covered files

Tests run against the real component runtime via convex-test (@edge-runtime/vm), not mocks.

Contributing

See CONTRIBUTING.md.

Author

Built by bntvllnt · bntvllnt.com · X @bntvllnt

Part of the @vllnt Convex component fleet — vllnt.com

If this is useful, sponsor the work.

License

MIT — see LICENSE.