@kindgi/api 0.1.4 → 0.1.5-rc.0

package/src/service-account-binding.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { ProjectRole } from '@kindgi/platform';
+import type { Cursor, Result, TenantId, Timestamp } from '@kindgi/types';
+
+/**
+ * Service accounts: named, non-human principals (`service_account:<id>`)
+ * for an app, a pipeline or a schedule's runs. A service account holds
+ * its own grants, set when it's created and changed by a tenant admin,
+ * and acts through API keys minted for it (`POST /v1/tokens` with `for`),
+ * several at once for rotation. Every route needs a tenant admin.
+ *
+ * Grants are written before a call answers, so a key minted for a new
+ * account works on its first request. Unregistering an account is a
+ * tombstone: its grants go, its keys stop working, and it stays readable.
+ */
+
+/**
+ * What a service account may do: tenant admin, tenant member (read the
+ * tenant's settings), or a role on one project. Unlike a person, an
+ * account isn't a tenant member unless it's granted that.
+ */
+export type ServiceAccountGrant =
+  | { readonly kind: 'tenant-admin' }
+  | { readonly kind: 'tenant-member' }
+  | { readonly kind: 'project'; readonly projectId: string; readonly role: ProjectRole };
+
+/** A grant to remove: tenant admin, tenant member, or whatever role the account has on a project. */
+export type ServiceAccountGrantTarget =
+  | { readonly kind: 'tenant-admin' }
+  | { readonly kind: 'tenant-member' }
+  | { readonly kind: 'project'; readonly projectId: string };
+
+export interface ServiceAccount {
+  readonly serviceAccountId: string;
+  readonly tenantId: TenantId;
+  /** Unique among the tenant's active accounts, e.g. `acme-ci`. */
+  readonly name: string;
+  readonly description?: string;
+  /** Its grants, at the time of the read. */
+  readonly grants: readonly ServiceAccountGrant[];
+  /** Who created it: `user:<id>` or `service_account:<id>`. */
+  readonly createdBy?: string;
+  readonly createdAt: Timestamp;
+  /** Set once unregistered: no grants, and its keys no longer work. */
+  readonly unregisteredAt?: Timestamp;
+}
+
+export interface ServiceAccountCreateInput {
+  readonly tenantId: TenantId;
+  readonly name: string;
+  readonly description?: string;
+  /** Written with the account, before `create` returns. */
+  readonly grants: readonly ServiceAccountGrant[];
+  readonly createdBy?: string;
+}
+
+export interface ServiceAccountRef {
+  readonly tenantId: TenantId;
+  readonly serviceAccountId: string;
+}
+
+/** A change to an account, and who made it: `user:<id>` or `service_account:<id>`. */
+export interface ServiceAccountChange extends ServiceAccountRef {
+  readonly by?: string;
+}
+
+export interface ServiceAccountListInput {
+  readonly tenantId: TenantId;
+  readonly limit: number;
+  readonly cursor?: Cursor;
+  /** Unregistered accounts too (default: active only). */
+  readonly includeUnregistered?: boolean;
+}
+
+export type ServiceAccountErrorCode =
+  /** An active account of the tenant already has this name. */
+  | 'service-account-name-taken'
+  | 'service-account-not-found'
+  /** A grant for an unregistered account. */
+  | 'service-account-unregistered'
+  /** A grant names a project the tenant doesn't have. */
+  | 'project-not-found';
+
+export interface ServiceAccountError {
+  readonly code: ServiceAccountErrorCode;
+  readonly message: string;
+}
+
+export interface ServiceAccountBinding {
+  create(input: ServiceAccountCreateInput): Promise<Result<ServiceAccount, ServiceAccountError>>;
+  /** Unregistered accounts too, or `null`. */
+  get(input: ServiceAccountRef): Promise<ServiceAccount | null>;
+  /** Oldest first. */
+  list(input: ServiceAccountListInput): Promise<{
+    readonly data: readonly ServiceAccount[];
+    readonly nextCursor?: Cursor;
+  }>;
+  /**
+   * Add a grant (a no-op when held). A project role replaces the
+   * account's role on that project. Not for an unregistered account.
+   */
+  grant(
+    input: ServiceAccountChange & { readonly grant: ServiceAccountGrant },
+  ): Promise<Result<ServiceAccount, ServiceAccountError>>;
+  /** Remove a grant (a no-op when not held). */
+  ungrant(
+    input: ServiceAccountChange & { readonly grant: ServiceAccountGrantTarget },
+  ): Promise<Result<ServiceAccount, ServiceAccountError>>;
+  /** Tombstone the account: its grants go and its keys stop working. Idempotent. */
+  unregister(input: ServiceAccountChange): Promise<Result<ServiceAccount, ServiceAccountError>>;
+}

package/src/session-store-binding.ts

@@ -13,15 +13,19 @@ import type { Cursor, SessionId, TenantId, Timestamp, UserId } from '@kindgi/typ
  * `POST /v1/auth/callback/:providerId` exchanges the authorization code
  * for provider tokens, fetches the userinfo, and calls
  * `SessionStoreBinding.create` to persist the resulting session; the
- * route then hands the caller an opaque framework-issued token
- * (`kgi_sk_<sessionId>`) that never leaks the provider access-token or
- * refresh-token to the client.
+ * route then hands the caller an opaque session token (`kgi_sk_…`) that
+ * never leaks the provider access-token or refresh-token to the client.
  *
- * The bearer-auth middleware routes session-token requests through
- * `get(tenantId, sessionId)`; the resolver hot path runs on every
- * authenticated request that carries a session token, so implementations
- * SHOULD keep `get` cheap (e.g. a single indexed lookup by id and
- * expiry, or a cache).
+ * A store that implements `resolveToken` owns the token: `create` mints it
+ * (returned once, as `token`), the store keeps only a hash, and the
+ * bearer-auth middleware hands every `kgi_sk_` token to `resolveToken`.
+ * A store without it gets the older token, `kgi_sk_<sessionId>`, which
+ * the middleware resolves through `get` with `MULTI_TENANT_LOOKUP`;
+ * anyone who can read such a store's session ids can use the sessions.
+ *
+ * The resolver hot path runs on every authenticated request that carries
+ * a session token, so implementations SHOULD keep it cheap (a single
+ * indexed lookup, or a cache).
  */
 export interface SessionStoreBinding {
   create(input: SessionCreateInput): Promise<SessionCreateOutput>;
@@ -29,6 +33,21 @@ export interface SessionStoreBinding {
   list(input: SessionListInput): Promise<SessionPage>;
   revoke(input: SessionRevokeInput): Promise<SessionRevokeOutcome>;
   revokeAllForUser(input: SessionRevokeAllForUserInput): Promise<SessionRevokeAllForUserOutcome>;
+  /**
+   * The session a token names, or `null` when it names none: an unknown,
+   * malformed or tampered token, or one in a format this store didn't
+   * mint. The store reads the token's tenant from the token itself and
+   * looks only in that tenant, comparing a hash of the token with what it
+   * stored (in constant time); nothing is read across tenants before the
+   * token is authenticated.
+   *
+   * A revoked, rotated or expired session is still returned (with
+   * `revokedAt`, `rotatedAt`, `expiresAt`): the middleware says which.
+   *
+   * When present, the middleware never calls `get` with
+   * `MULTI_TENANT_LOOKUP`, and `create` must return `token`.
+   */
+  readonly resolveToken?: (input: SessionResolveTokenInput) => Promise<Session | null>;
   /**
    * Update the session's `lastActiveAt` marker. Called by the auth
    * middleware on each successful authenticated request (throttled, by
@@ -36,10 +55,31 @@ export interface SessionStoreBinding {
    * doesn't hot-spot under load). Absent = the middleware only enforces absolute
    * TTL; inactivity timeout is disabled.
    *
-   * The tenant sentinel `MULTI_TENANT_LOOKUP` is honored the same way
-   * as `get` — the middleware doesn't know the tenant ahead of time.
+   * The middleware passes the session's own tenant. A store without
+   * `resolveToken` must also honor the sentinel `MULTI_TENANT_LOOKUP`,
+   * as `get` does.
    */
   readonly touch?: (input: SessionTouchInput) => Promise<SessionTouchOutcome>;
+  /**
+   * End every live session one provider opened, in one tenant: the console
+   * sessions an API key opened (`api-token:<tokenId>`, from token sign-in)
+   * when it's revoked; an identity provider's sign-ins when it's removed.
+   * Absent → those sessions run until they expire.
+   */
+  readonly revokeByProvider?: (
+    input: SessionRevokeByProviderInput,
+  ) => Promise<SessionRevokeAllForUserOutcome>;
+}
+
+export interface SessionRevokeByProviderInput {
+  readonly tenantId: TenantId;
+  /** The `providerId` the sessions were created with. */
+  readonly providerId: string;
+}
+
+export interface SessionResolveTokenInput {
+  /** The whole token, as the caller sent it (`kgi_sk_…`). */
+  readonly token: string;
 }
 
 export interface SessionCreateInput {
@@ -47,8 +87,12 @@ export interface SessionCreateInput {
   readonly userId: UserId;
   /** ProviderId of the `IdentityProviderBinding` that authenticated the user. */
   readonly providerId: string;
-  /** Opaque provider access-token — server-side only. */
-  readonly accessToken: string;
+  /**
+   * Opaque provider access-token, server-side only. Absent when the
+   * deployment keeps no identity-provider tokens (a sign-in that only
+   * establishes who the person is).
+   */
+  readonly accessToken?: string;
   /** Opaque provider refresh-token — server-side only, may be absent. */
   readonly refreshToken?: string;
   readonly expiresAt: Timestamp;
@@ -60,6 +104,13 @@ export interface SessionCreateInput {
 export interface SessionCreateOutput {
   readonly sessionId: SessionId;
   readonly expiresAt: Timestamp;
+  /**
+   * The session token the store minted, returned this once (the store
+   * keeps only its hash). Required from a store that implements
+   * `resolveToken`; absent from an older store, whose token is
+   * `kgi_sk_<sessionId>`.
+   */
+  readonly token?: string;
 }
 
 export interface SessionGetInput {
@@ -99,7 +150,8 @@ export interface Session {
   readonly tenantId: TenantId;
   readonly userId: UserId;
   readonly providerId: string;
-  readonly accessToken: string;
+  /** Absent when the deployment keeps no identity-provider tokens. */
+  readonly accessToken?: string;
   readonly refreshToken?: string;
   readonly expiresAt: Timestamp;
   readonly scopes: readonly string[];

package/src/signed-export.ts

@@ -0,0 +1,250 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+/**
+ * Signed exports: one envelope and one signing path for the three
+ * exports a deployment signs (an approval's audit bundle, a run's
+ * provenance, compliance evidence).
+ *
+ * The envelope carries the exact bytes that were signed (`bundle`,
+ * base64 of the sorted-key JSON body), so a verifier checks those bytes
+ * and never re-serializes anything. `exportedAt` is inside the signed
+ * body, and the envelope's copy is the same value.
+ *
+ * Each export is recorded as an `export-signed` audit event (who, what,
+ * which key, the bundle's SHA-256) when the app has an audit-event
+ * binding. Recording comes before the bundle is returned: a bundle the
+ * record couldn't be written for isn't handed out.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+
+import type { AuditEvent, AuditEventBinding } from '@kindgi/audit-events';
+import type {
+  ExportSigningAlgorithm,
+  ExportSigningBinding,
+  ExportSigningError,
+} from '@kindgi/crypto';
+import { canonicalize } from '@kindgi/schema';
+import type { ProjectId, TenantId, Timestamp } from '@kindgi/types';
+import type { Context } from 'hono';
+
+import { statusFor, toWireError } from './errors.js';
+import type { AppEnv } from './types.js';
+
+export type SignedExportKind = 'audit-bundle' | 'provenance' | 'compliance';
+
+/** The audit-event kind each signed export is recorded under. */
+export const EXPORT_SIGNED_EVENT_KIND = 'export-signed';
+
+/** What every signed export answers, before its subject field (`approvalId`, `runId`, `tenantId`). */
+export interface SignedExportEnvelope {
+  readonly kind: SignedExportKind;
+  /** Base64 of the signed bytes: the body, as sorted-key JSON. */
+  readonly bundle: string;
+  readonly bundleSchemaVersion: string;
+  /** The signing key's algorithm: `ed25519`, or `ecdsa-p256-sha256` for a KMS without Ed25519. */
+  readonly algorithm: ExportSigningAlgorithm;
+  readonly signingKeyId: string;
+  /**
+   * Base64 of the signature over the `bundle` bytes: 64 bytes either way,
+   * Ed25519's, or ECDSA P-256's as IEEE P1363 `r‖s`.
+   */
+  readonly signature: string;
+  /** The signing key's public half, PEM SPKI. Check it against `GET /v1/export-signing-keys`. */
+  readonly publicKey: string;
+  readonly canonicalization: 'sorted-key-json';
+  /** The same instant as the signed body's `exportedAt`. */
+  readonly exportedAt: string;
+}
+
+export interface SignExportInput {
+  readonly signer: ExportSigningBinding;
+  readonly kind: SignedExportKind;
+  readonly bundleSchemaVersion: string;
+  /** The body without `bundleSchemaVersion` and `exportedAt`: both are added, and signed. */
+  readonly body: Readonly<Record<string, unknown>>;
+  readonly signingKeyId?: string;
+  readonly now?: () => Date;
+  /** Record the export (an `export-signed` audit event) before answering. */
+  readonly record?: {
+    readonly auditEvents: AuditEventBinding;
+    readonly tenantId: TenantId;
+    readonly projectId?: ProjectId;
+    readonly runId?: string;
+    readonly actor: string;
+    /** The exported thing: `{ approvalId }`, `{ runId }`, or the compliance filter. */
+    readonly subject: Readonly<Record<string, unknown>>;
+  };
+}
+
+export type SignExportError =
+  | ExportSigningError
+  | { readonly code: 'persistence-error'; readonly message: string };
+
+/** Sign an export's body and, when asked, record it. */
+export async function signExport(
+  input: SignExportInput,
+): Promise<
+  | { readonly kind: 'ok'; readonly value: SignedExportEnvelope }
+  | { readonly kind: 'err'; readonly error: SignExportError }
+> {
+  const exportedAt = (input.now?.() ?? new Date()).toISOString();
+  const body = { ...input.body, bundleSchemaVersion: input.bundleSchemaVersion, exportedAt };
+  const bytes = new TextEncoder().encode(canonicalize(body));
+  const signed = await input.signer.sign(
+    bytes,
+    input.signingKeyId !== undefined ? { keyId: input.signingKeyId } : undefined,
+  );
+  if (signed.kind === 'err') return signed;
+  const envelope: SignedExportEnvelope = {
+    kind: input.kind,
+    bundle: Buffer.from(bytes).toString('base64'),
+    bundleSchemaVersion: input.bundleSchemaVersion,
+    algorithm: signed.value.key.algorithm,
+    signingKeyId: signed.value.key.keyId,
+    signature: Buffer.from(signed.value.signature).toString('base64'),
+    publicKey: signed.value.key.publicKeyPem,
+    canonicalization: 'sorted-key-json',
+    exportedAt,
+  };
+  if (input.record !== undefined) {
+    const recorded = await recordExport(input.record, envelope, bytes);
+    if (recorded !== undefined) return { kind: 'err', error: recorded };
+  }
+  return { kind: 'ok', value: envelope };
+}
+
+async function recordExport(
+  record: NonNullable<SignExportInput['record']>,
+  envelope: SignedExportEnvelope,
+  bytes: Uint8Array,
+): Promise<SignExportError | undefined> {
+  const event: AuditEvent = {
+    id: randomUUID(),
+    tenantId: record.tenantId,
+    ...(record.projectId !== undefined && { projectId: record.projectId }),
+    kind: EXPORT_SIGNED_EVENT_KIND,
+    timestamp: envelope.exportedAt as unknown as Timestamp,
+    actor: record.actor,
+    ...(record.runId !== undefined && { runId: record.runId }),
+    outcome: 'succeeded',
+    payload: {
+      v: 1,
+      doc: {
+        exportKind: envelope.kind,
+        subject: record.subject,
+        signingKeyId: envelope.signingKeyId,
+        bundleSha256: createHash('sha256').update(bytes).digest('hex'),
+        bundleSchemaVersion: envelope.bundleSchemaVersion,
+        exportedAt: envelope.exportedAt,
+      },
+    },
+  };
+  const appended = await record.auditEvents.append([event]);
+  if (appended.kind === 'ok') return undefined;
+  return {
+    code: 'persistence-error',
+    message: `The export was signed, but recording it failed, so it isn't returned: ${appended.error.message}. Try again.`,
+  };
+}
+
+/**
+ * An export request's body: JSON, an object, or nothing at all (read as
+ * `{}`, so `curl -X POST` and a bodiless POST work).
+ */
+export async function readExportBody(
+  c: Context<AppEnv>,
+): Promise<
+  | { readonly kind: 'ok'; readonly value: Record<string, unknown> }
+  | { readonly kind: 'err'; readonly message: string }
+> {
+  const text = await c.req.text();
+  if (text.trim() === '') return { kind: 'ok', value: {} };
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return { kind: 'err', message: 'Request body must be valid JSON' };
+  }
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { kind: 'err', message: 'Request body must be an object' };
+  }
+  return { kind: 'ok', value: body as Record<string, unknown> };
+}
+
+/** `signingKeyId`, when the body names one: a non-empty string. */
+export function parseSigningKeyId(
+  body: Readonly<Record<string, unknown>>,
+):
+  | { readonly kind: 'ok'; readonly value: string | undefined }
+  | { readonly kind: 'err'; readonly message: string } {
+  if (!('signingKeyId' in body) || body.signingKeyId === undefined) {
+    return { kind: 'ok', value: undefined };
+  }
+  const raw = body.signingKeyId;
+  if (typeof raw !== 'string' || raw.length === 0) {
+    return {
+      kind: 'err',
+      message:
+        'Field `signingKeyId` must be a non-empty string when present; leave it out to sign with the active key.',
+    };
+  }
+  return { kind: 'ok', value: raw };
+}
+
+/** `404 signing-not-configured`: this deployment has no export signing key. */
+export function signingNotConfigured(c: Context<AppEnv>, what: string): Response {
+  c.status(statusFor('signing-not-configured') as never);
+  return c.json(
+    toWireError(
+      {
+        code: 'signing-not-configured',
+        message: `This deployment doesn't sign exports, so ${what} are unavailable: it has no export signing key. On the Kindgi runtime, set KINDGI_EXPORT_SIGNING_KEY_PATH, KINDGI_EXPORT_SIGNING_KEY or KINDGI_EXPORT_SIGNING_KMS_KEY.`,
+      },
+      c.get('requestId'),
+    ),
+  );
+}
+
+/**
+ * A `signExport` failure as the route answers it: `404
+ * signing-key-not-found`, `500 persistence-error`, or `500` with
+ * `failureCode` (each route keeps the code it answered before).
+ */
+export function signExportFailure(
+  c: Context<AppEnv>,
+  error: SignExportError,
+  failureCode: 'export-key-error' | 'compliance-export-failed',
+): Response {
+  const requestId = c.get('requestId');
+  if (error.code === 'signing-key-not-found') {
+    c.status(statusFor('signing-key-not-found') as never);
+    return c.json(
+      toWireError(
+        { code: 'signing-key-not-found', message: error.message, signingKeyId: error.keyId },
+        requestId,
+      ),
+    );
+  }
+  if (error.code === 'persistence-error') {
+    c.status(statusFor('persistence-error') as never);
+    return c.json(toWireError({ code: 'persistence-error', message: error.message }, requestId));
+  }
+  c.status(statusFor(failureCode) as never);
+  return c.json(
+    toWireError(
+      { code: failureCode, message: `Signing the export failed: ${error.message}` },
+      requestId,
+    ),
+  );
+}
+
+/** The caller as an audit actor: `user:<id>`, `service_account:<tokenId>`, or `service_account:unknown`. */
+export function exportActor(c: Context<AppEnv>): string {
+  const userId = c.get('userId');
+  if (userId !== undefined) return `user:${userId as unknown as string}`;
+  const tokenId = c.get('tokenId');
+  if (tokenId !== undefined) return `service_account:${tokenId as unknown as string}`;
+  return 'service_account:unknown';
+}