@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/src/identity-provider-binding.ts

@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged catalog of OAuth 2.0 / OIDC identity providers the
+ * deployment offers to its tenants. Same pattern as
+ * `ProviderRegistryBinding` (model providers) — the API package does
+ * NOT own provider persistence, and secrets never cross the wire.
+ *
+ * A `ProviderConfig` carries ONLY a `clientSecretRef` — an opaque
+ * pointer that the deployment resolves server-side (env-var lookup,
+ * secrets-manager path, KMS handle, etc.). The plaintext client secret
+ * is exchanged with the identity provider inside the deployment's
+ * boundary during the code→token exchange in `/v1/auth/callback` and
+ * never surfaces on any HTTP response.
+ *
+ * PKCE is mandatory (S256). Providers that don't support PKCE are
+ * rejected at boot; the framework does NOT emit `code_challenge_method`
+ * negotiation.
+ */
+export interface IdentityProviderBinding {
+  list(input: IdentityProviderListInput): Promise<IdentityProviderPage>;
+  get(input: IdentityProviderGetInput): Promise<ProviderConfig | null>;
+  register(input: IdentityProviderRegisterInput): Promise<IdentityProviderRegisterOutcome>;
+  unregister(input: IdentityProviderUnregisterInput): Promise<IdentityProviderUnregisterOutcome>;
+}
+
+export type IdentityProviderKind = 'oauth2' | 'oidc';
+
+export interface ProviderConfig {
+  /** Stable string chosen by the deployment (e.g. `acme-sso`, `globex-oidc`). */
+  readonly providerId: string;
+  readonly kind: IdentityProviderKind;
+  readonly clientId: string;
+  /**
+   * Opaque pointer resolved server-side. Never a plaintext secret. The
+   * shape (env-var name / secrets-manager path / KMS handle) is a
+   * deployment convention, not a framework one.
+   */
+  readonly clientSecretRef: string;
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly userinfoEndpoint?: string;
+  readonly scopes: readonly string[];
+  /**
+   * OAuth 2.1 BCP redirect-URI allowlist. When present and non-empty,
+   * `POST /v1/auth/login/:providerId` rejects any `redirectUri` (whether
+   * supplied in the body or resolved from `metadata.defaultRedirectUri`)
+   * that is not an exact match to a list entry — 400
+   * `redirect-uri-not-allowed`. `POST /v1/auth/callback/:providerId`
+   * cross-checks the state row's stored `redirect_uri` against the same
+   * list — 400 `redirect-uri-mismatch` if the allowlist was tightened
+   * between login and callback. Absent or empty → any redirect_uri is
+   * accepted (pass-through; deployments MUST populate
+   * this to reach OAuth 2.1 BCP compliance).
+   *
+   * Exact-string match, not prefix or regex — the OAuth 2.1 BCP
+   * mandates literal comparison to prevent redirect-URI injection.
+   */
+  readonly allowedRedirectUris?: readonly string[];
+  /**
+   * Optional per-provider claim mapping. When present, the `ExchangeCodeFn`
+   * / `RefreshTokenFn` implementations translate provider claims into the
+   * Kindgi `Session` shape according to this spec. Absent → pass-
+   * through (provider `sub` → `userId`, `email` → `email`, `name` →
+   * `displayName`, scopes come from the token response). A deployment's
+   * own `ExchangeCodeFn` MAY honor this field the same way.
+   */
+  readonly claimMapping?: ClaimMappingSpec;
+  readonly metadata?: Record<string, unknown>;
+}
+
+/**
+ * How provider claims map into Kindgi's session shape. All fields
+ * are optional — the closer a provider's claim naming is to the OIDC
+ * defaults (`sub` / `email` / `name`), the fewer overrides the
+ * deployment needs. Field values are dot-path claim references
+ * relative to the provider's userinfo / id_token payload:
+ *
+ * - `"sub"` reads top-level `sub`.
+ * - `"profile.email"` reads `payload.profile.email` (dot-navigated).
+ * - `"https://acme.com/roles"` reads the raw claim under that URI-
+ *   shaped key (namespaced custom claims — no dot navigation).
+ *
+ * The scopes case is a discriminated shape because scope claims in
+ * the wild come as either space-separated strings, comma-separated,
+ * or a JSON array — the `delimiter` field lets deployments say how to
+ * split. When omitted (or the resolved claim is already an array),
+ * splitting is skipped.
+ */
+export interface ClaimMappingSpec {
+  /** Provider claim path for the Kindgi `userId`. Default: `sub`. */
+  readonly userId?: string;
+  /** Provider claim path for the caller's email. Default: `email`. */
+  readonly email?: string;
+  /** Provider claim path for the caller's display name. Default: `name`. */
+  readonly displayName?: string;
+  /**
+   * Provider claim path + optional delimiter for the Kindgi OAuth
+   * scopes list. When absent, scopes come from the OAuth token
+   * response `scope` field, not from claims.
+   */
+  readonly scopes?: ClaimMappingScopesSpec;
+  /**
+   * Extra claim paths to preserve verbatim on `Session.metadata`.
+   * Values are copied as-is. Absent → all claims flow through in
+   * `metadata`.
+   */
+  readonly metadata?: readonly string[];
+}
+
+export interface ClaimMappingScopesSpec {
+  /** Claim path for the raw scopes value. */
+  readonly claim: string;
+  /**
+   * When the resolved claim is a string, split on this delimiter to
+   * produce the scopes array. When absent, split on any whitespace.
+   * Ignored when the resolved claim is already an array.
+   */
+  readonly delimiter?: string;
+}
+
+export interface IdentityProviderListInput {
+  readonly tenantId: TenantId;
+}
+
+export interface IdentityProviderPage {
+  readonly data: readonly ProviderConfig[];
+}
+
+export interface IdentityProviderGetInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+}
+
+export interface IdentityProviderRegisterInput {
+  readonly tenantId: TenantId;
+  readonly config: ProviderConfig;
+}
+
+export type IdentityProviderRegisterOutcome = {
+  readonly kind: 'ok';
+  readonly providerId: string;
+};
+
+export interface IdentityProviderUnregisterInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+}
+
+export interface IdentityProviderUnregisterOutcome {
+  readonly unregistered: boolean;
+}
+
+/**
+ * Result of the OAuth code→session exchange the callback route delegates
+ * to the identity provider. Distinct from `SessionCreateInput` because
+ * the framework decides the `SessionId` (opaque), while the provider
+ * decides `userId` / `accessToken` / `scopes`.
+ */
+export interface ExchangeCodeInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+  readonly code: string;
+  readonly codeVerifier: string;
+  readonly redirectUri: string;
+}
+
+export interface ExchangeCodeOutcome {
+  readonly userId: string;
+  readonly accessToken: string;
+  readonly refreshToken?: string;
+  readonly expiresAt: Date;
+  readonly scopes: readonly string[];
+  readonly claims?: Record<string, unknown>;
+}
+
+/**
+ * Optional companion binding used by `POST /v1/auth/callback` and
+ * `POST /v1/auth/refresh`. Deployments that only implement provider
+ * registry CRUD (and want to run the exchange themselves) can inline
+ * this closure via `CreateAppInput.exchangeCode`. A typical
+ * implementation calls the provider `tokenEndpoint` with PKCE +
+ * client-secret client authentication.
+ */
+export type ExchangeCodeFn = (input: ExchangeCodeInput) => Promise<ExchangeCodeOutcome>;
+
+/**
+ * Optional refresh-token exchange. When present, `POST /v1/auth/refresh`
+ * rotates the underlying provider tokens before minting a new session
+ * token. When absent, the refresh route simply revokes the old session
+ * and re-issues a session token with the same expiry (still useful for
+ * key rotation on the framework side even when the provider stays put).
+ */
+export interface RefreshTokenInput {
+  readonly tenantId: TenantId;
+  readonly providerId: string;
+  readonly refreshToken: string;
+}
+
+export type RefreshTokenFn = (input: RefreshTokenInput) => Promise<ExchangeCodeOutcome>;

package/src/image-registry-binding.ts

@@ -0,0 +1,193 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import type { Result, TenantId } from '@kindgi/types';
+
+/**
+ * Caller-plugged surface for the OCI image registry — the "Docker
+ * Registry HTTP API v2 client" seam used by the deploy route's
+ * image-verifiability step. Mirrors the caller-plugged pattern of
+ * `BlobStorageBinding`: the API package does NOT own registry auth or
+ * connectivity. Deployments plug in an adapter that talks to whichever
+ * OCI registry they run — hosted or self-hosted — using the credentials
+ * they operate.
+ *
+ * Three ops per the OCI Distribution Spec:
+ *   - `head`         — read manifest metadata (digest, config, layer
+ *                      digests, size) without pulling bytes. Used at
+ *                      `POST /v1/deployments` to verify the pinned
+ *                      digest exists + matches what the deployer signed.
+ *   - `extractFile`  — pull the bytes of a single file inside the image
+ *                      (typically `/app/index.json`) without downloading
+ *                      every layer. Used by the deploy route to verify
+ *                      `indexHash` matches `sha256(image's index.json)`.
+ *   - `push`         — upload a locally-built image + tag. Used by an
+ *                      image build step; the API only reads.
+ *
+ * Each method is tenant-scoped so multi-tenant deployments can route
+ * different tenants at different registries (or the same registry with
+ * per-tenant credentials).
+ *
+ * ## Seam only
+ *
+ * No concrete implementation is bundled; the `POST /v1/deployments`
+ * route calls `head` + `extractFile` through this interface.
+ */
+export interface ImageRegistryBinding {
+  /**
+   * Read the OCI image manifest for a digest-pinned reference. Returns
+   * `image-not-found` when the registry has no manifest at the given
+   * digest; `image-registry-unreachable` on transport / auth failure.
+   *
+   * The route MUST verify that `descriptor.digest` matches the digest
+   * inside `input.imageRef` — the binding is not responsible for that
+   * cross-check (defense-in-depth against a compromised registry).
+   */
+  head(input: ImageHeadInput): Promise<Result<ImageDescriptor, ImageRegistryError>>;
+  /**
+   * Fetch the bytes of a single file inside the image's layered
+   * filesystem. Implementations stream from the highest layer that
+   * contains the path — e.g. traverse layers top-down and return the
+   * first hit. `bytes` is streamed as a
+   * `Uint8Array` (small files only — `/app/index.json` is expected to
+   * be a few kilobytes to low megabytes).
+   *
+   * Returns `image-file-not-found` when no layer contains the path,
+   * `image-not-found` when the ref itself is unresolvable.
+   */
+  extractFile(input: ImageExtractFileInput): Promise<Result<ImageFile, ImageRegistryError>>;
+  /**
+   * Push a locally-built image + tag. Used by the build service, not by
+   * the API — but the interface exposes it so the same binding
+   * satisfies both consumers (a single deployment operator can wire one
+   * adapter across the whole framework).
+   *
+   * `bytes` is an OCI image archive (`docker save`-compatible tarball
+   * or a streaming OCI layout). The binding walks it, uploads each
+   * blob + manifest, and tags the final digest. Returns the resolved
+   * digest-pinned reference for the caller to sign over.
+   */
+  push(input: ImagePushInput): Promise<Result<ImagePushOutcome, ImageRegistryError>>;
+}
+
+// -------------------- descriptor --------------------
+
+/**
+ * Slice of the OCI manifest the API layer + build service need. Keeps
+ * the interface stable against future spec revisions — bindings extract
+ * the parts every consumer cares about and hide the rest.
+ */
+export interface ImageDescriptor {
+  /** `sha256:<hex>` — canonical image digest, matches `imageRef`. */
+  readonly digest: string;
+  /** OCI media type of the manifest (`application/vnd.oci.image.manifest.v1+json` etc.). */
+  readonly mediaType: string;
+  /** Total on-wire size in bytes across all layers + config. */
+  readonly size: number;
+  /** Layer descriptors, top-to-bottom (the order used at pull time). */
+  readonly layers: readonly ImageLayerDescriptor[];
+  /** Image config descriptor (histories, env, entrypoint, etc.). */
+  readonly config: ImageBlobDescriptor;
+  /** `platform` from the manifest (e.g. `linux/amd64`). */
+  readonly platform?: ImagePlatform;
+}
+
+export interface ImageLayerDescriptor {
+  readonly digest: string;
+  readonly mediaType: string;
+  readonly size: number;
+}
+
+export type ImageBlobDescriptor = ImageLayerDescriptor;
+
+export interface ImagePlatform {
+  readonly os: string;
+  readonly architecture: string;
+  readonly variant?: string;
+}
+
+// -------------------- head --------------------
+
+export interface ImageHeadInput {
+  readonly tenantId: TenantId;
+  /** Full digest-pinned reference: `<host>/<repo>@sha256:<hex>`. */
+  readonly imageRef: string;
+}
+
+// -------------------- extractFile --------------------
+
+export interface ImageExtractFileInput {
+  readonly tenantId: TenantId;
+  readonly imageRef: string;
+  /**
+   * Absolute path inside the image's layered filesystem. Convention:
+   * leading slash + POSIX separators (`/app/index.json`).
+   */
+  readonly path: string;
+}
+
+export interface ImageFile {
+  readonly path: string;
+  readonly bytes: Uint8Array;
+  /** `sha256` hex, lowercase — computed over `bytes` by the binding. */
+  readonly sha256: string;
+  /** Layer digest the file was found in — useful for audit logs. */
+  readonly layerDigest: string;
+}
+
+// -------------------- push --------------------
+
+export interface ImagePushInput {
+  readonly tenantId: TenantId;
+  /**
+   * Unresolved reference the pusher requests — usually
+   * `<host>/<repo>:<tag>`. The binding uploads the archive and returns
+   * the digest-pinned form on success.
+   */
+  readonly imageRef: string;
+  /** OCI image archive bytes. */
+  readonly bytes: ReadableStream<Uint8Array> | Uint8Array;
+  /** Optional annotations the binding forwards to the registry. */
+  readonly annotations?: Readonly<Record<string, string>>;
+}
+
+export interface ImagePushOutcome {
+  /** Digest-pinned reference the caller signs against. */
+  readonly imageRef: string;
+  readonly digest: string;
+  readonly size: number;
+}
+
+// -------------------- error --------------------
+
+/**
+ * Discriminated error union. The deploy route reports any of these as
+ * `400 image-unverifiable` ("we could not verify this image"), carrying
+ * the binding's `code` as `cause`.
+ */
+export type ImageRegistryError =
+  | {
+      readonly code: 'image-not-found';
+      readonly message: string;
+      readonly imageRef: string;
+    }
+  | {
+      readonly code: 'image-file-not-found';
+      readonly message: string;
+      readonly imageRef: string;
+      readonly path: string;
+    }
+  | {
+      readonly code: 'image-registry-unreachable';
+      readonly message: string;
+      readonly cause?: unknown;
+    }
+  | {
+      readonly code: 'image-registry-unauthorized';
+      readonly message: string;
+    }
+  | {
+      readonly code: 'image-push-failed';
+      readonly message: string;
+      readonly cause?: unknown;
+    };