@kindgi/api 0.1.4 → 0.1.5

package/src/testing/app-bindings.ts

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ConversationBinding, RunSnapshotBinding } from '@kindgi/agents';
+import type { MemoryQueryBinding } from '@kindgi/memory';
+import type { TenantHierarchyBinding } from '@kindgi/platform';
+import type {
+  KernelBinding,
+  RunBinding,
+  RunRetentionBinding,
+  SchedulerBinding,
+  TriggerRegistryBinding,
+  WaitpointBinding,
+} from '@kindgi/runtime';
+import type { CreateAppInput } from '../app.js';
+
+import { createStubBinding } from './stub-binding.js';
+
+/**
+ * The bindings `createApp` requires that tests usually don't exercise —
+ * everything in `CreateAppInput` that is mandatory except the
+ * caller-specific `resolveToken` and `runHandler`.
+ */
+export type StubAppBindings = Pick<
+  CreateAppInput,
+  | 'conversationBinding'
+  | 'runSnapshotBinding'
+  | 'kernelBinding'
+  | 'tenantHierarchyBinding'
+  | 'memoryBinding'
+  | 'provenanceBinding'
+>;
+
+/**
+ * Stubs for every required `createApp` binding. Mount the API for
+ * contract, route-shape, and handler tests without a database or the
+ * Kindgi runtime; any route that reaches one of these bindings fails
+ * loudly with a `StubBindingError` naming the binding and method.
+ *
+ * Override the ones a test needs:
+ *
+ * ```ts
+ * const app = createApp({
+ *   ...createStubAppBindings(),
+ *   resolveToken,
+ *   runHandler,
+ *   agentRegistry: myInMemoryAgentRegistry,
+ * });
+ * ```
+ */
+export function createStubAppBindings(): StubAppBindings {
+  return {
+    conversationBinding: createStubBinding<ConversationBinding>('conversationBinding', {
+      openConversation: true,
+      getConversation: true,
+      listConversations: true,
+      listConversationsPage: true,
+      closeConversation: true,
+      unregisterConversation: true,
+      deleteConversation: true,
+      appendMessage: true,
+      readMessages: true,
+    }),
+    runSnapshotBinding: createStubBinding<RunSnapshotBinding>('runSnapshotBinding', {
+      write: true,
+      read: true,
+    }),
+    kernelBinding: createStubKernelBinding(),
+    tenantHierarchyBinding: createStubBinding<TenantHierarchyBinding>('tenantHierarchyBinding', {
+      createOrg: true,
+      createTeam: true,
+      createProject: true,
+      addTeamMember: true,
+      addProjectMember: true,
+      removeTeamMember: true,
+      updateTeamMemberRole: true,
+      removeProjectMember: true,
+      updateProjectMemberRole: true,
+      getTenant: true,
+    }),
+    memoryBinding: createStubBinding<MemoryQueryBinding>('memoryBinding', {
+      listFacts: true,
+      searchByKeyword: true,
+      searchBySemantic: true,
+      appendLog: true,
+      readLog: true,
+      searchConversations: true,
+    }),
+    provenanceBinding: createStubBinding<CreateAppInput['provenanceBinding']>('provenanceBinding', {
+      listRecords: true,
+      getByRunId: true,
+      getCallUsage: true,
+    }),
+  };
+}
+
+/**
+ * Stub `KernelBinding`: each sub-binding is a stub named
+ * `kernelBinding.<sub>`. The optional `eventBus` is omitted (absent), so
+ * code that feature-checks it takes the no-event-bus path.
+ */
+export function createStubKernelBinding(): KernelBinding {
+  return {
+    run: createStubBinding<RunBinding>('kernelBinding.run', {
+      runGraph: true,
+      resumeRun: true,
+      cancelRun: true,
+      cancelToken: true,
+      completeToken: true,
+      readJournal: true,
+      startRun: true,
+      deleteRun: true,
+      getRun: true,
+      listRuns: true,
+    }),
+    scheduler: createStubBinding<SchedulerBinding>('kernelBinding.scheduler', {
+      startCronScheduler: true,
+      startEventTriggerScheduler: true,
+      fireByWebhookId: true,
+      initialNextFireAt: true,
+    }),
+    waitpoint: createStubBinding<WaitpointBinding>('kernelBinding.waitpoint', {
+      startTimeoutSleeper: true,
+    }),
+    retention: createStubBinding<RunRetentionBinding>('kernelBinding.retention', {
+      createRetentionAdapter: true,
+    }),
+    triggers: createStubBinding<TriggerRegistryBinding>('kernelBinding.triggers', {
+      register: true,
+      update: true,
+      list: true,
+      get: true,
+      pause: true,
+      resume: true,
+      unregister: true,
+      fetchActiveByWebhookId: true,
+      listFires: true,
+      fireNow: true,
+      setOwner: true,
+    }),
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * `@kindgi/api/testing`: typed, fail-loud stub bindings for `createApp`,
+ * for tests that mount the API without a database or the Kindgi runtime.
+ * They live here, beside the `CreateAppInput` they stub, so `@kindgi/api`'s
+ * own tests use them without depending on `@kindgi/testing` (which
+ * re-exports them, unchanged).
+ */
+
+export {
+  createStubAppBindings,
+  createStubKernelBinding,
+  type StubAppBindings,
+} from './app-bindings.js';
+export { StubBindingError, createStubBinding, type StubMethods } from './stub-binding.js';
+export {
+  createInMemoryTriggerRegistry,
+  type InMemoryTriggerRegistry,
+} from './trigger-registry.js';

package/src/testing/stub-binding.ts

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Thrown when code under test calls a method on a stub binding. The
+ * message names the binding and method so the fix — supply a real
+ * implementation or a test double for that binding — is obvious.
+ */
+export class StubBindingError extends Error {
+  readonly binding: string;
+  readonly method: string;
+
+  constructor(binding: string, method: string) {
+    super(
+      `${binding}.${method}() was called on a stub binding from @kindgi/testing. ` +
+        `Pass a real implementation or a test double for \`${binding}\` to exercise this code path.`,
+    );
+    this.name = 'StubBindingError';
+    this.binding = binding;
+    this.method = method;
+  }
+}
+
+/**
+ * One `true` entry per method of `T`. Typed as a complete mapping, so a
+ * method added to the interface (or a stale one left behind) fails to
+ * compile at the stub definition instead of slipping through at runtime.
+ */
+export type StubMethods<T> = { readonly [K in keyof T]-?: true };
+
+/**
+ * Build a stub implementation of the binding interface `T`: every method
+ * listed in `methods` throws {@link StubBindingError} when called.
+ *
+ * ```ts
+ * const memory = createStubBinding<MemoryQueryBinding>('memoryBinding', {
+ *   listFacts: true,
+ *   searchByKeyword: true,
+ *   searchBySemantic: true,
+ *   appendLog: true,
+ *   readLog: true,
+ * });
+ * ```
+ */
+export function createStubBinding<T extends object>(name: string, methods: StubMethods<T>): T {
+  const stub: Record<string, () => never> = {};
+  for (const method of Object.keys(methods)) {
+    stub[method] = () => {
+      throw new StubBindingError(name, method);
+    };
+  }
+  return stub as T;
+}

package/src/testing/trigger-registry.ts

@@ -0,0 +1,259 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { randomUUID } from 'node:crypto';
+
+import {
+  type CronTriggerRecord,
+  type ListTriggerFiresInput,
+  type RegisterTriggerInput,
+  SCHEDULE_DEFAULTS,
+  type TriggerFire,
+  type TriggerFirePage,
+  type TriggerLifecycleInput,
+  type TriggerOwner,
+  type TriggerRecord,
+  type TriggerRegistryBinding,
+  type UpdateTriggerInput,
+} from '@kindgi/runtime';
+import type { Cursor, ProjectId, TenantId, TriggerId } from '@kindgi/types';
+
+/**
+ * An in-memory `TriggerRegistryBinding` for app and route tests: the
+ * admin surface over stored triggers, with fire history and `run-now`.
+ * It computes no occurrences (`nextFireAt` stays `null`) and starts no
+ * runs; `fireNow` records a `pending` fire, and `recordFire` lets a test
+ * add fires as a scheduler would.
+ */
+export interface InMemoryTriggerRegistry extends TriggerRegistryBinding {
+  /** Add a fire to a trigger's history, as a scheduler would. */
+  recordFire(fire: Omit<TriggerFire, 'fireId'> & { readonly fireId?: string }): TriggerFire;
+}
+
+export function createInMemoryTriggerRegistry(
+  options: {
+    /** The project a schedule registered without one goes to. */
+    readonly defaultProjectId?: ProjectId;
+    readonly now?: () => Date;
+  } = {},
+): InMemoryTriggerRegistry {
+  const rows = new Map<string, TriggerRecord & { unregistered?: boolean }>();
+  const fires: TriggerFire[] = [];
+  const now = () => (options.now ?? (() => new Date()))().toISOString();
+  const defaultProject =
+    options.defaultProjectId ?? ('00000000-0000-4000-8000-000000000000' as ProjectId);
+
+  const live = (tenantId: TenantId, triggerId: TriggerId) => {
+    const row = rows.get(triggerId as unknown as string);
+    return row !== undefined && row.tenantId === tenantId && row.unregistered !== true
+      ? row
+      : undefined;
+  };
+  const notFound = (triggerId: TriggerId) => ({
+    kind: 'err' as const,
+    error: {
+      code: 'trigger-not-found' as const,
+      message: `No trigger "${triggerId as unknown as string}"`,
+      triggerId,
+    },
+  });
+  const save = (row: TriggerRecord): TriggerRecord => {
+    rows.set(row.triggerId as unknown as string, row);
+    return row;
+  };
+  const strip = (row: TriggerRecord & { unregistered?: boolean }): TriggerRecord => {
+    const { unregistered: _, ...rest } = row;
+    return rest as TriggerRecord;
+  };
+
+  const registry: InMemoryTriggerRegistry = {
+    async register(input: RegisterTriggerInput) {
+      const base = {
+        triggerId: randomUUID() as TriggerId,
+        tenantId: input.tenantId,
+        status: 'active' as const,
+        label: input.label ?? null,
+        lastFiredAt: null,
+        createdAt: now(),
+        updatedAt: now(),
+      };
+      if (input.kind === 'cron') {
+        return {
+          kind: 'ok',
+          value: save({
+            ...base,
+            kind: 'cron',
+            target: input.target,
+            projectId: input.projectId ?? defaultProject,
+            owner: input.owner,
+            config: input.config,
+            catchUp: input.catchUp ?? SCHEDULE_DEFAULTS.catchUp,
+            overlap: input.overlap ?? SCHEDULE_DEFAULTS.overlap,
+            startingDeadlineSeconds:
+              input.startingDeadlineSeconds ?? SCHEDULE_DEFAULTS.startingDeadlineSeconds,
+            nextFireAt: null,
+          }),
+        };
+      }
+      const flow = { flowId: input.flowId, flowVersion: input.flowVersion };
+      return {
+        kind: 'ok',
+        value: save(
+          input.kind === 'event'
+            ? { ...base, ...flow, kind: 'event', config: input.config }
+            : {
+                ...base,
+                ...flow,
+                kind: 'webhook',
+                config: input.config,
+                webhookId: input.webhookId,
+                hmacSecretName: input.hmacSecretName,
+              },
+        ),
+      };
+    },
+
+    async update(input: UpdateTriggerInput) {
+      const row = live(input.tenantId, input.triggerId);
+      if (row === undefined || row.kind !== input.kind) return notFound(input.triggerId);
+      const common = {
+        updatedAt: now(),
+        ...(input.label !== undefined && { label: input.label }),
+      };
+      if (row.kind === 'cron' && input.kind === 'cron') {
+        return {
+          kind: 'ok',
+          value: save({
+            ...row,
+            ...common,
+            config: { ...row.config, ...input.config },
+            ...(input.target !== undefined && { target: input.target }),
+            ...(input.catchUp !== undefined && { catchUp: input.catchUp }),
+            ...(input.overlap !== undefined && { overlap: input.overlap }),
+            ...(input.startingDeadlineSeconds !== undefined && {
+              startingDeadlineSeconds: input.startingDeadlineSeconds,
+            }),
+          } as CronTriggerRecord),
+        };
+      }
+      return {
+        kind: 'ok',
+        value: save({
+          ...row,
+          ...common,
+          config: { ...row.config, ...input.config },
+          ...(input.kind !== 'cron' &&
+            input.flowVersion !== undefined && { flowVersion: input.flowVersion }),
+        } as TriggerRecord),
+      };
+    },
+
+    async list(input) {
+      const all = [...rows.values()]
+        .filter(
+          (r) =>
+            r.tenantId === input.tenantId &&
+            r.unregistered !== true &&
+            (input.kind === undefined || r.kind === input.kind) &&
+            (input.status === undefined || r.status === input.status),
+        )
+        .map(strip);
+      const start = input.cursor === undefined ? 0 : Number(input.cursor);
+      const limit = input.limit ?? 50;
+      const data = all.slice(start, start + limit);
+      return {
+        data,
+        ...(start + limit < all.length && { nextCursor: String(start + limit) as Cursor }),
+      };
+    },
+
+    async get(input) {
+      const row = live(input.tenantId, input.triggerId);
+      return row === undefined ? null : strip(row);
+    },
+
+    async pause(input: TriggerLifecycleInput) {
+      return setStatus(input, 'paused');
+    },
+
+    async resume(input: TriggerLifecycleInput) {
+      return setStatus(input, 'active');
+    },
+
+    async unregister(input) {
+      const row = live(input.tenantId, input.triggerId);
+      if (row === undefined) return { triggerId: input.triggerId, unregistered: false };
+      rows.set(input.triggerId as unknown as string, { ...row, unregistered: true });
+      return { triggerId: input.triggerId, unregistered: true };
+    },
+
+    async fetchActiveByWebhookId(input) {
+      const row = [...rows.values()].find(
+        (r) =>
+          r.kind === 'webhook' &&
+          r.tenantId === input.tenantId &&
+          r.webhookId === input.webhookId &&
+          r.status === 'active' &&
+          r.unregistered !== true,
+      );
+      return row?.kind === 'webhook' ? row : null;
+    },
+
+    async listFires(input: ListTriggerFiresInput): Promise<TriggerFirePage> {
+      const mine = fires
+        .filter((f) => f.triggerId === input.triggerId && live(input.tenantId, f.triggerId))
+        .reverse();
+      const start = input.cursor === undefined ? 0 : Number(input.cursor);
+      const limit = input.limit ?? 50;
+      return {
+        data: mine.slice(start, start + limit),
+        ...(start + limit < mine.length && { nextCursor: String(start + limit) as Cursor }),
+      };
+    },
+
+    async fireNow(input: TriggerLifecycleInput) {
+      const row = live(input.tenantId, input.triggerId);
+      if (row === undefined || row.kind !== 'cron') return notFound(input.triggerId);
+      return {
+        kind: 'ok',
+        value: registry.recordFire({
+          triggerId: input.triggerId,
+          kind: 'schedule',
+          firedAt: now(),
+          outcome: 'pending',
+          manual: true,
+        }),
+      };
+    },
+
+    async setOwner(input: TriggerLifecycleInput & { readonly owner: TriggerOwner }) {
+      const row = live(input.tenantId, input.triggerId);
+      if (row === undefined || row.kind !== 'cron') return notFound(input.triggerId);
+      return { kind: 'ok', value: save({ ...row, owner: input.owner, updatedAt: now() }) };
+    },
+
+    recordFire(fire) {
+      const recorded: TriggerFire = { ...fire, fireId: fire.fireId ?? randomUUID() };
+      fires.push(recorded);
+      return recorded;
+    },
+  };
+
+  async function setStatus(input: TriggerLifecycleInput, status: 'active' | 'paused') {
+    const row = live(input.tenantId, input.triggerId);
+    if (row === undefined) return notFound(input.triggerId);
+    if (row.status === status) {
+      return {
+        kind: 'err' as const,
+        error: {
+          code: 'trigger-already-in-state' as const,
+          message: `The trigger is already ${status}`,
+          triggerId: input.triggerId,
+        },
+      };
+    }
+    return { kind: 'ok' as const, value: save({ ...row, status, updatedAt: now() }) };
+  }
+
+  return registry;
+}

package/src/token-admin.ts

@@ -9,29 +9,46 @@ import type { ApiTokenId, ProjectId, TenantId } from '@kindgi/types';
  * Splitting keeps the auth hot path free of write concerns and lets
  * deployments plug in different implementations.
  *
- * An API key is a machine credential: a service account
- * (`service_account:<tokenId>`) with a role in its tenant and an explicit
- * list of framework capabilities. `POST /v1/tokens` mints;
- * `GET /v1/tokens` and `GET /v1/tokens/:tokenId` read (never the secret);
+ * An API key always acts for one principal (`TokenPrincipal`): a person
+ * (`user:<id>`) or a service account (`service_account:<id>`), with that
+ * principal's grants and nothing more. Its `role` is a ceiling under those
+ * grants, and its `projectId` narrows it to one project; neither ever
+ * widens it. `POST /v1/tokens` mints; `GET /v1/tokens` and
+ * `GET /v1/tokens/:tokenId` read (never the secret);
  * `POST /v1/tokens/:tokenId/revoke` revokes.
  */
 export interface TokenAdmin {
-  mint(input: TokenMintInput): Promise<TokenMintOutput>;
+  /** The new key and its secret, or why the store refused it. */
+  mint(input: TokenMintInput): Promise<TokenMintOutput | TokenMintRefusal>;
   list(input: TokenListInput): Promise<readonly ApiTokenRecord[]>;
   get(input: TokenGetInput): Promise<ApiTokenRecord | undefined>;
   revoke(input: TokenRevokeInput): Promise<TokenRevokeOutcome>;
 }
 
 /**
- * A key's role in its tenant. `admin` administers the tenant (and mints,
- * lists and revokes keys); `member` belongs to it and administers nothing.
+ * A key's role: the most it may do, under its principal's grants. An
+ * `admin` key may administer the tenant when its principal can; a `member`
+ * key administers nothing, even when its principal is an admin (a
+ * day-to-day key that can't change keys, grants or policies).
  */
 export type ApiTokenRole = 'admin' | 'member';
 
 export const API_TOKEN_ROLES: readonly ApiTokenRole[] = ['admin', 'member'];
 
+/** Whom a key acts for: a person, or a service account. */
+export type TokenPrincipal =
+  | { readonly kind: 'user'; readonly userId: string }
+  | { readonly kind: 'service-account'; readonly serviceAccountId: string };
+
 export interface TokenMintInput {
   readonly tenantId: TenantId;
+  /**
+   * Whom the key acts for: the caller, unless a tenant admin names
+   * someone else. Absent when a tenant admin whose token names no
+   * principal mints for themselves; the key is then a service account of
+   * its own, as every key was before principals.
+   */
+  readonly principal?: TokenPrincipal;
   readonly role: ApiTokenRole;
   /**
    * Framework capabilities the key carries (`env:write`, `secrets:write`,
@@ -42,7 +59,7 @@ export interface TokenMintInput {
   readonly label?: string;
   /** Optional expiration date. */
   readonly expiresAt?: Date;
-  /** Optional project scope; when set, tokens are only valid for that project. */
+  /** Optional project: the key is narrowed to it, refused on any other. */
   readonly projectId?: ProjectId;
   /**
    * Who minted it, as a principal reference: `user:<id>` or
@@ -51,6 +68,15 @@ export interface TokenMintInput {
   readonly createdBy?: string;
 }
 
+/**
+ * A mint the store refused: the principal doesn't exist (or is
+ * unregistered), or an `admin` key for a principal that isn't a tenant
+ * admin.
+ */
+export type TokenMintRefusal =
+  | { readonly kind: 'principal-not-found'; readonly message: string }
+  | { readonly kind: 'role-exceeds-principal'; readonly message: string };
+
 export interface TokenMintOutput {
   /** The new key, as `list` and `get` will show it. */
   readonly record: ApiTokenRecord;
@@ -65,6 +91,8 @@ export interface TokenMintOutput {
 /** What a key looks like after minting: everything but its secret. */
 export interface ApiTokenRecord {
   readonly tokenId: ApiTokenId;
+  /** Whom it acts for. Absent from stores built before principals. */
+  readonly principal?: TokenPrincipal;
   readonly role: ApiTokenRole;
   readonly capabilities: readonly string[];
   readonly label?: string;
@@ -87,6 +115,8 @@ export interface ApiTokenRecord {
 export interface TokenListInput {
   readonly tenantId: TenantId;
   readonly limit: number;
+  /** Only the keys that act for this principal (a person sees only their own). */
+  readonly principal?: TokenPrincipal;
   /** The last record of the previous page. */
   readonly after?: { readonly createdAt: Date; readonly tokenId: ApiTokenId };
 }
@@ -99,6 +129,8 @@ export interface TokenGetInput {
 export interface TokenRevokeInput {
   readonly tenantId: TenantId;
   readonly tokenId: ApiTokenId;
+  /** Who revoked it: `user:<id>` or `service_account:<id>`. */
+  readonly revokedBy?: string;
 }
 
 export type TokenRevokeOutcome = { readonly kind: 'ok' } | { readonly kind: 'not-found' };

package/src/tool-binding.ts

@@ -96,6 +96,8 @@ export interface ToolRegistryBinding {
    * same `(toolId, version)` is re-published; the route maps that to
    * `409`. Semver hygiene: version numbers are single-use even after
    * unregister — reinstate instead of republishing the same bytes.
+   * A version of a tool whose versions live in another project is
+   * `project-mismatch` (tools never move between projects; `409 tool-project-mismatch`).
    */
   publish(input: ToolPublishInput): Promise<ToolPublishOutcome>;
   /**
@@ -236,6 +238,18 @@ export type ToolPublishOutcome =
       readonly toolId: ToolId;
       readonly version: Semver;
       readonly projectId: ProjectId;
+    }
+  | {
+      /**
+       * The tool's versions live in another project: a tool belongs to
+       * the project its first version was published into, and never
+       * moves. Nothing is written (the route answers `409 tool-project-mismatch`).
+       */
+      readonly kind: 'project-mismatch';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+      /** The project the tool belongs to. */
+      readonly projectId: ProjectId;
     };
 
 export type ToolUnregisterOutcome = {

package/src/trigger-binding.ts

@@ -16,18 +16,25 @@ export type {
   CronTriggerRecord,
   EventTriggerRecord,
   GetTriggerInput,
+  ListTriggerFiresInput,
   ListTriggersInput,
   RegisterCronTriggerInput,
   RegisterEventTriggerInput,
   RegisterTriggerError,
   RegisterTriggerInput,
   RegisterWebhookTriggerInput,
+  ScheduleCatchUp,
+  ScheduleOverlap,
+  TriggerFire,
+  TriggerFirePage,
   TriggerKind,
   TriggerLifecycleError,
   TriggerLifecycleInput,
   TriggerListPage,
   TriggerRecord,
+  TriggerOwner,
   TriggerRegistryBinding,
+  TriggerTarget,
   UpdateCronTriggerInput,
   UpdateEventTriggerInput,
   UpdateTriggerError,
@@ -35,4 +42,4 @@ export type {
   UpdateWebhookTriggerInput,
   WebhookTriggerRecord,
 } from '@kindgi/runtime';
-export { TRIGGER_KINDS } from '@kindgi/runtime';
+export { SCHEDULE_DEFAULTS, TRIGGER_KINDS } from '@kindgi/runtime';

package/src/types.ts

@@ -42,6 +42,20 @@ export interface AppEnv {
      * account.
      */
     tokenId?: ApiTokenId;
+    /** The service account an API key acts for. */
+    serviceAccountId?: string;
+    /**
+     * Set by a route whose answer carries a secret (`withholdFromReplay`):
+     * the Idempotency-Key middleware keeps that the request succeeded, not
+     * its answer.
+     */
+    idempotencyWithhold?: boolean;
+    /** An API key's role ceiling (`member` keys can't administer the tenant). */
+    tokenRole?: 'admin' | 'member';
+    /** The project an API key is narrowed to. */
+    tokenProjectId?: string;
+    /** When the API token the request came with expires, if it does. */
+    tokenExpiresAt?: Date;
     /**
      * Set by `bearerAuthMiddleware` when the caller presented a
      * framework-issued OAuth session token (`kgi_sk_*`).
@@ -49,6 +63,8 @@ export interface AppEnv {
      * revoke without a second lookup. Absent for static bearer tokens.
      */
     sessionId?: SessionId;
+    /** Set when the session token came from a cookie (not a header): that cookie's name. */
+    sessionCookieName?: string;
     /** Identity-provider id behind a session token. Absent for bearer. */
     providerId?: string;
     /** Set by `sigv4Middleware` on `/s3/*`: the bucket the credential may access. */