Skip to content
Kumiko

personal-access-tokens

Long-lived, revocable Personal Access Tokens for headless HTTP-API access. Stores SHA-256 token hashes in the store_api_tokens direct-write table; the plaintext is returned once at creation. create/revoke/mine manage a user’s own tokens and available-scopes lists the app-declared scope catalog. Bearer tokens carrying the PAT prefix are resolved before jwt.verify (roles resolved live, granted scopes enforced fail-closed at the API boundary) — registered as an auth-foundation tokenVerifier provider, resolved generically by the middleware. Pass { toggleable: { default: false } } to tier-gate the whole feature.

Quick example

Section titled “Quick example”

From apps-use-all-bundled — the smallest working mount:

// Smoke-entrypoint for use-all-bundled. CI runs this with
// KUMIKO_DRY_RUN_ENV=boot to exercise validators across every bundled
// feature without an actual postgres/redis. See package.json `boot`
// script + ../README.md.


import { frameworkCoreEnvSchema } from "@cosmicdrift/kumiko-dev-server/env-schema";
import { InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
import { composeEnvSchema } from "@cosmicdrift/kumiko-framework/env";
import { runProdApp } from "@cosmicdrift/kumiko-server-runtime";
import { BUNDLED_LISTS } from "../src/bundled-lists";
import {
  APP_FEATURES,
  AUTH_COMPOSE_OPTIONS,
  BOOT_FEATURES,
  VALIDATE_BOOT_OPTIONS,
} from "../src/run-config";


const SMOKE_TENANT_ID = "00000000-0000-4000-8000-000000000001" as TenantId;


const envSchema = composeEnvSchema({
  core: frameworkCoreEnvSchema,
  features: APP_FEATURES,
});


await runProdApp({
  features: BOOT_FEATURES,
  featureToggles: true,
  envSchema,
  validateBootOptions: VALIDATE_BOOT_OPTIONS,
  bundledLists: BUNDLED_LISTS,
  // Smoke-only: exercises the hard PII boot gate + blind-index gate with
  // every bundled feature mounted. Real apps wire createPgKmsAdapter(...).
  kms: new InMemoryKmsAdapter(),
  blindIndexKey: Buffer.alloc(32, 7).toString("base64"),
  // migrations default ("./kumiko/migrations") — boot mode exits before the
  // schema drift gate, the path here is only the runProdApp default.
  // auth.admin triggers composeFeatures(includeBundled:true) — auto-mounts
  // config + user + tenant + auth-email-password. Boot mode exits
  // before admin seeding runs, the value is only a stub for the types.
  auth: {
    admin: {
      email: "smoke@use-all-bundled.local",
      password: "smoke-only-never-deployed",
      displayName: "Smoke Admin",
      memberships: [
        {
          tenantId: SMOKE_TENANT_ID,
          tenantKey: "smoke",
          tenantName: "Use-All-Bundled Smoke",
          roles: ["TenantAdmin"],
        },
      ],
    },
    // Coverage for auth-self-registration toggle (#1521 Option A).
    signup: AUTH_COMPOSE_OPTIONS.signup,
    invite: AUTH_COMPOSE_OPTIONS.invite,
    passwordReset: AUTH_COMPOSE_OPTIONS.passwordReset,
    emailVerification: AUTH_COMPOSE_OPTIONS.emailVerification,
    accountUnlock: AUTH_COMPOSE_OPTIONS.accountUnlock,
  },
});

📄 On GitHub: samples/apps/use-all-bundled/bin/main.ts

How it fits

Section titled “How it fits”

What this feature needs to run (Requires, top) and the write commands this feature provides (Provides, bottom).

flowchart TB
  n_personal_access_tokens["personal-access-tokens"]
  subgraph how_reqs["Requires"]
    n_user["user"]
    n_tenant["tenant"]
    n_auth_foundation["auth-foundation"]
  end
  subgraph how_provides["Provides"]
    n_cmd_personal_access_tokens_write_create(["create"])
    n_cmd_personal_access_tokens_write_revoke(["revoke"])
  end
  n_user --> n_personal_access_tokens
  n_tenant --> n_personal_access_tokens
  n_auth_foundation --> n_personal_access_tokens
  n_personal_access_tokens --> n_cmd_personal_access_tokens_write_create
  n_personal_access_tokens --> n_cmd_personal_access_tokens_write_revoke

Provides — write commands this feature registers (dispatch them through the command bus):

Getting started

Section titled “Getting started”

Start with apps-use-all-bundled for a step-by-step walkthrough with runnable code and integration tests.

Dependencies

Section titled “Dependencies”

Extensions & cross-feature APIs

Section titled “Extensions & cross-feature APIs”
  • Registers extension: tokenVerifier → pat