@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/token-admin.ts

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ApiTokenId, ProjectId, TenantId } from '@kindgi/types';
+
+/**
+ * Admin surface for API keys: mint, list, read, revoke. Distinct from
+ * `TokenResolver`, which is the read path used by the auth middleware.
+ * 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);
+ * `POST /v1/tokens/:tokenId/revoke` revokes.
+ */
+export interface TokenAdmin {
+  mint(input: TokenMintInput): Promise<TokenMintOutput>;
+  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.
+ */
+export type ApiTokenRole = 'admin' | 'member';
+
+export const API_TOKEN_ROLES: readonly ApiTokenRole[] = ['admin', 'member'];
+
+export interface TokenMintInput {
+  readonly tenantId: TenantId;
+  readonly role: ApiTokenRole;
+  /**
+   * Framework capabilities the key carries (`env:write`, `secrets:write`,
+   * …). The route only lets a caller grant capabilities it holds itself.
+   */
+  readonly capabilities: readonly string[];
+  /** Optional human-readable label. Shown in admin UIs. */
+  readonly label?: string;
+  /** Optional expiration date. */
+  readonly expiresAt?: Date;
+  /** Optional project scope; when set, tokens are only valid for that project. */
+  readonly projectId?: ProjectId;
+  /**
+   * Who minted it, as a principal reference: `user:<id>` or
+   * `service_account:<tokenId>`.
+   */
+  readonly createdBy?: string;
+}
+
+export interface TokenMintOutput {
+  /** The new key, as `list` and `get` will show it. */
+  readonly record: ApiTokenRecord;
+  /**
+   * The plaintext bearer token. Returned to the caller ONCE, at mint
+   * time. Stores must persist a hash — not the plaintext — so lost
+   * tokens can only be replaced, not recovered.
+   */
+  readonly token: string;
+}
+
+/** What a key looks like after minting: everything but its secret. */
+export interface ApiTokenRecord {
+  readonly tokenId: ApiTokenId;
+  readonly role: ApiTokenRole;
+  readonly capabilities: readonly string[];
+  readonly label?: string;
+  readonly projectId?: ProjectId;
+  readonly createdBy?: string;
+  readonly createdAt: Date;
+  readonly expiresAt?: Date;
+  /** Set once revoked. A revoked key never resolves again. */
+  readonly revokedAt?: Date;
+  /** When the key last authenticated a request (updated at most once a minute). */
+  readonly lastUsedAt?: Date;
+}
+
+/**
+ * A page of keys, newest first (`createdAt` then `tokenId`, descending).
+ * The store returns up to `limit` records strictly after `after` in that
+ * order; the route asks for one more than it shows, to know whether more
+ * remain.
+ */
+export interface TokenListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  /** The last record of the previous page. */
+  readonly after?: { readonly createdAt: Date; readonly tokenId: ApiTokenId };
+}
+
+export interface TokenGetInput {
+  readonly tenantId: TenantId;
+  readonly tokenId: ApiTokenId;
+}
+
+export interface TokenRevokeInput {
+  readonly tenantId: TenantId;
+  readonly tokenId: ApiTokenId;
+}
+
+export type TokenRevokeOutcome = { readonly kind: 'ok' } | { readonly kind: 'not-found' };

package/src/tool-binding.ts

@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TupleEnqueueHook } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { ToolManifest } from '@kindgi/tools';
+import type { Cursor, ProjectId, Semver, TenantId, ToolId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the tool catalog. Versioned CRUD mirroring
+ * `AgentRegistryBinding` — the API package does NOT own registry
+ * persistence. Deployments wire a `ToolRegistry` (from `@kindgi/tools`)
+ * — or a durable store — through this binding.
+ *
+ * The surface is metadata-only: a `Tool` runtime value carries a
+ * `handler` closure, which cannot cross HTTP. The wire body is a
+ * `ToolManifest` (Tool minus handler); the actual handler must already
+ * be registered with the runtime. Handler code is not uploaded over
+ * this surface.
+ *
+ * `publish` is versioned — each call adds a new `(toolId,
+ * version)` row. `get(toolId)` returns the latest active version;
+ * agents reference tools via `{ id, version: <semver-range> }` and
+ * `resolve(toolId, versionSpec)` walks active versions to pick the
+ * highest satisfying via `semver.maxSatisfying`. Retirement follows the
+ * versioned soft-tombstone pattern: `unregister(toolId, version)`
+ * soft-tombstones one version; `reinstateVersion` un-tombstones; when no
+ * active versions remain, the tool has no latest version and
+ * `GET /v1/tools/{id}` returns 410 gone (distinct from 404
+ * not-found via `headExists`).
+ */
+export interface ToolRegistryBinding {
+  /**
+   * Cursor-paginated list of tools (latest active version per id).
+   * Optional `nameFilter` is a prefix match on the tool id — tools use
+   * dotted namespaces (`acme.verify-citation`), so prefix matching is
+   * the natural filter shape. Derived-retired tools (no active
+   * versions) are hidden from list by default.
+   */
+  list(input: ToolListInput): Promise<ToolPage>;
+  /**
+   * The manifest of the LATEST active version for the given tool id,
+   * or `null` if the id is unknown OR every version is tombstoned.
+   * The route uses `headExists` to distinguish 410 gone from 404
+   * not-found.
+   */
+  get(input: ToolGetInput): Promise<ToolManifest | null>;
+  /**
+   * Exact `(toolId, version)` lookup, including tombstoned versions.
+   * Provenance paths use this to resolve historical run references.
+   */
+  getVersion(input: ToolGetVersionInput): Promise<ToolManifest | null>;
+  /**
+   * Cursor-paginated list of versions for a specific tool id. Sort
+   * order is binding-defined (for example, publish timestamp
+   * descending). Returns an empty page (no
+   * error) when the id is unknown — the route flips that to 404 via
+   * a prior `headExists`.
+   *
+   * By default returns only active versions. Set
+   * `includeTombstoned = true` to include soft-tombstoned rows too;
+   * tombstoned rows carry `unregisteredAt` on the wire (ISO string),
+   * active rows do not.
+   */
+  listVersions(input: ToolListVersionsInput): Promise<ToolVersionPage>;
+  /**
+   * Head-row existence probe. Lets `GET /v1/tools/{id}` distinguish
+   * `410 gone` (identity exists, no active version) from `404 not-
+   * found` (never registered). Same shape as
+   * `AgentRegistryBinding.headExists`.
+   */
+  headExists(input: ToolGetInput): Promise<boolean>;
+  /**
+   * Resolve a semver range against active versions and return the
+   * highest satisfying manifest via `semver.maxSatisfying`. When
+   * `versionSpec` is absent, returns the latest active version (same
+   * as `get`). `not-satisfiable` fires when the range parses but no
+   * active version matches. `invalid-range` fires when the range
+   * itself is not valid semver grammar. `not-found` fires when the
+   * tool id is unknown.
+   */
+  resolve(input: ToolResolveInput): Promise<ToolResolveOutcome>;
+  /**
+   * Publish a validated tool manifest. Every publish adds a version
+   * row; the tool's latest version is recomputed across active
+   * versions. Bindings MAY reject with `already-registered` when the
+   * 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.
+   */
+  publish(input: ToolPublishInput): Promise<ToolPublishOutcome>;
+  /**
+   * Soft-tombstone a specific `(toolId, version)`. When this leaves
+   * NO active versions, the tool has no latest version — it enters the
+   * derived "retired" state (GET returns 410 gone).
+   * Publish of a new version reactivates. Version is REQUIRED
+   * (there are no bare-tool-id semantics).
+   */
+  unregister(input: ToolUnregisterInput): Promise<ToolUnregisterOutcome>;
+  /**
+   * Un-tombstone a specific `(toolId, version)`. Recomputes the tool's
+   * latest version across active versions. Restores the manifest
+   * bytes verbatim (semver hygiene). Idempotent.
+   */
+  reinstateVersion(input: ToolReinstateVersionInput): Promise<ToolReinstateVersionOutcome>;
+}
+
+export interface ToolListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Prefix match on `ToolManifest.id`. Undefined = no filter. */
+  readonly nameFilter?: string;
+  /**
+   * Narrow the list to a specific scope. Absent = no scope narrow
+   * (return every row in the tenant the caller can see).
+   */
+  readonly scope?: Scope;
+  /**
+   * `false` = literal-at-this-scope only. `true` (default) =
+   * inheritance walk — no-op for content-scoped bindings
+   * (documented for uniformity).
+   */
+  readonly inherit?: boolean;
+}
+
+export interface ToolGetInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+}
+
+export interface ToolGetVersionInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+  readonly version: Semver;
+}
+
+export interface ToolListVersionsInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /**
+   * `false` (default) → return only active versions. `true` → return
+   * active + tombstoned rows; tombstoned entries carry `unregisteredAt`
+   * on the wire, active entries do not. Aligns with the soft-tombstone
+   * pattern used by agents / flows / eval suites / policies.
+   */
+  readonly includeTombstoned?: boolean;
+}
+
+export interface ToolResolveInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+  /**
+   * Semver range (npm grammar): `'1.2.3'` exact pin, `'^1.2.3'`
+   * compatible-updates, `'~1.2.3'` patch-updates, `'>=1.0.0 <2.0.0'`
+   * explicit range. Absent = latest active (behaves like `get`).
+   */
+  readonly versionSpec?: string;
+}
+
+export interface ToolPublishInput {
+  readonly tenantId: TenantId;
+  /**
+   * Project the tool is registered into. REQUIRED. Callers
+   * that don't naturally know a projectId (deployment
+   * route, boot-time dev-echo seed, MCP bridge) resolve the tenant's
+   * Default via `projectBinding.getDefault(tenantId)` at THEIR layer.
+   */
+  readonly projectId: ProjectId;
+  readonly tool: ToolManifest;
+  /**
+   * REQUIRED. Called inside the binding's write tx after row insert,
+   * receiving the business `toolId`. Returns tuples for the same tx.
+   * See `AgentPublishInput.enqueueTuples` for the design rationale.
+   */
+  readonly enqueueTuples: TupleEnqueueHook;
+}
+
+export interface ToolUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+  /** REQUIRED — no bare-id unregister under the versioned model. */
+  readonly version: Semver;
+}
+
+export interface ToolReinstateVersionInput {
+  readonly tenantId: TenantId;
+  readonly toolId: ToolId;
+  readonly version: Semver;
+}
+
+export interface ToolPage {
+  readonly data: readonly ToolManifest[];
+  readonly nextCursor?: Cursor;
+}
+
+/**
+ * A single row in a `listVersions` result. Manifest fields plus an
+ * optional `unregisteredAt` timestamp — present iff the version has
+ * been soft-tombstoned via `unregister`. Callers that ignore the extra
+ * field see a plain `ToolManifest`.
+ */
+export type ToolVersionRow = ToolManifest & {
+  readonly unregisteredAt?: string;
+};
+
+export interface ToolVersionPage {
+  readonly data: readonly ToolVersionRow[];
+  readonly nextCursor?: Cursor;
+}
+
+export type ToolPublishOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+    }
+  | {
+      readonly kind: 'already-registered';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+    }
+  | {
+      readonly kind: 'project-not-found';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+      readonly projectId: ProjectId;
+    };
+
+export type ToolUnregisterOutcome = {
+  readonly unregistered: boolean;
+};
+
+export type ToolReinstateVersionOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+      readonly wasTombstoned: boolean;
+    }
+  | {
+      readonly kind: 'not-found';
+      readonly toolId: ToolId;
+      readonly version: Semver;
+    };
+
+export type ToolResolveOutcome =
+  | {
+      readonly kind: 'ok';
+      readonly toolId: ToolId;
+      readonly resolvedVersion: Semver;
+      readonly manifest: ToolManifest;
+    }
+  | {
+      /** No `(toolId)` head row — tool id was never published. */
+      readonly kind: 'not-found';
+      readonly toolId: ToolId;
+    }
+  | {
+      /** Head exists but no active versions match the requested range. */
+      readonly kind: 'not-satisfiable';
+      readonly toolId: ToolId;
+      readonly versionSpec: string;
+      /** Active semver strings — helps the caller diagnose. */
+      readonly candidateVersions: readonly string[];
+    }
+  | {
+      /** `versionSpec` failed `semver.validRange`. */
+      readonly kind: 'invalid-range';
+      readonly toolId: ToolId;
+      readonly versionSpec: string;
+    };

package/src/trigger-binding.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Trigger registry — API-layer view of the runtime-owned CRUD contract.
+ *
+ * The interface lives in `@kindgi/runtime` (public wire vocabulary);
+ * the Kindgi runtime provides an implementation. The API layer
+ * re-exports the contract here for parity with the other caller-plugged
+ * bindings (`AdapterRegistryBinding`, `ProviderRegistryBinding`, etc.) —
+ * routes import from this file, deployments plug in a satisfying impl
+ * (their own, if they want bespoke persistence).
+ */
+
+export type {
+  CronTriggerRecord,
+  EventTriggerRecord,
+  GetTriggerInput,
+  ListTriggersInput,
+  RegisterCronTriggerInput,
+  RegisterEventTriggerInput,
+  RegisterTriggerError,
+  RegisterTriggerInput,
+  RegisterWebhookTriggerInput,
+  TriggerKind,
+  TriggerLifecycleError,
+  TriggerLifecycleInput,
+  TriggerListPage,
+  TriggerRecord,
+  TriggerRegistryBinding,
+  UpdateCronTriggerInput,
+  UpdateEventTriggerInput,
+  UpdateTriggerError,
+  UpdateTriggerInput,
+  UpdateWebhookTriggerInput,
+  WebhookTriggerRecord,
+} from '@kindgi/runtime';
+export { TRIGGER_KINDS } from '@kindgi/runtime';

package/src/types.ts

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Principal, ReviewerRole } from '@kindgi/authz';
+import type { ApiTokenId, RunId, SessionId, TenantId, UserId } from '@kindgi/types';
+
+/**
+ * Hono environment shape — variables the middleware chain populates
+ * and route handlers consume via `c.get(...)`.
+ */
+export interface AppEnv {
+  Variables: {
+    requestId: string;
+    /** Set by `bearerAuthMiddleware` on authenticated routes. */
+    tenantId: TenantId;
+    /**
+     * Set by `bearerAuthMiddleware` when the token's `TokenResolution`
+     * carried a `reviewerRole`. Approvals routes gate visibility +
+     * decisions on this: `standard < senior < admin`. Absent for
+     * tokens that were never provisioned with a reviewer role.
+     */
+    reviewerRole?: ReviewerRole;
+    /**
+     * Set by `bearerAuthMiddleware` when the token resolution carries
+     * a `userId`. Approvals routes hand it to `ReviewerBinding` to
+     * translate `UserId → ReviewerId` before calling `submitReview`.
+     */
+    userId?: UserId;
+    /**
+     * Set by `bearerAuthMiddleware` when the caller authenticated with a
+     * durable API key: the key's id. The principal is the key's service
+     * account.
+     */
+    tokenId?: ApiTokenId;
+    /**
+     * Set by `bearerAuthMiddleware` when the caller presented a
+     * framework-issued OAuth session token (`kgi_sk_*`).
+     * `/v1/identity/whoami` + `/v1/auth/logout` read this to introspect /
+     * revoke without a second lookup. Absent for static bearer tokens.
+     */
+    sessionId?: SessionId;
+    /** Identity-provider id behind a session token. Absent for bearer. */
+    providerId?: string;
+    /** Set by `sigv4Middleware` on `/s3/*`: the bucket the credential may access. */
+    bucket?: string;
+    /** Set by `sigv4Middleware` on `/s3/*`: the access key that signed the request. */
+    s3AccessKeyId?: string;
+    /** OAuth scopes granted to a session token. Absent for bearer. */
+    scopes?: readonly string[];
+    /**
+     * Framework capabilities granted to the bearer. Route handlers
+     * call `hasCapability(c, '<name>')` to gate
+     * writes / reveals; missing capability → 403 `permission-denied`.
+     * Absent = no capabilities granted.
+     */
+    capabilities?: readonly string[];
+    /**
+     * Composite authz Principal built by `principalMiddleware` from
+     * the token resolution. Present on every route mounted BELOW that
+     * middleware (i.e. all `/v1/*` routes). Consumed by the
+     * `authorize()` middleware factory and any route handler that
+     * needs to make conditional authz checks.
+     */
+    principal?: Principal;
+    /**
+     * Set when the request authenticated with a public run token
+     * (`kgi_pt_…`): such a request may only read the runs in
+     * `publicRunIds` and their descendants, on the progress routes.
+     */
+    tokenKind?: 'public-run';
+    /** The runs a public run token names. */
+    publicRunIds?: readonly RunId[];
+  };
+}