@kindgi/api 0.0.0-bootstrap.0 → 0.1.1

package/dist/routes/deployments.d.ts

@@ -0,0 +1,122 @@
+import { Hono } from 'hono';
+import type { ProjectBinding } from '@kindgi/platform';
+import type { AgentRegistryBinding } from '../agent-binding.js';
+import type { DeploymentBinding } from '../deployment-binding.js';
+import type { FlowRegistryBinding } from '../flow-binding.js';
+import type { GuardrailRegistryBinding } from '../guardrail-binding.js';
+import type { ImageRegistryBinding } from '../image-registry-binding.js';
+import type { SecretBinding } from '../secrets-binding.js';
+import type { SigningKeyBinding as SigningKeyRegistryBinding } from '../signing-key-binding.js';
+import type { ToolRegistryBinding } from '../tool-binding.js';
+import type { AppEnv } from '../types.js';
+import type { GuardrailWriteHook } from './guardrails.js';
+import type { ToolWriteHook } from './tools.js';
+/**
+ * Deployments resource routes — the landing surface for signed pack
+ * deploys:
+ *
+ *   - `POST /v1/deployments`                  — signed deployment (atomic).
+ *   - `GET  /v1/deployments`                  — cursor-paginated list.
+ *   - `GET  /v1/deployments/:deploymentId`    — single record.
+ *   - `POST /v1/deployments/:deploymentId/secrets` — deployment-scoped secret sync.
+ *
+ * ### Atomic transaction (POST)
+ *
+ * The route runs four verification steps IN ORDER (1–4 below) before any
+ * registry write, then does upserts + records deployment (5–6) as a single
+ * all-or-nothing unit. Any failure past the first upsert rolls back the successfully-
+ * inserted primitives so the tenant's catalog never observes a partial
+ * deploy.
+ *
+ *   1. Body shape (id/version/signature fields present + typed).
+ *   2. Signature — canonicalise `{imageDigest, artifactVersion,
+ *      indexHash, tenantId, publishedAt}` as sorted-key JSON (UTF-8,
+ *      no whitespace); verify with Ed25519 against `signerPublicKey`;
+ *      cross-check `(signerKeyId, publicKey)` on the tenant's trust
+ *      list via `SigningKeyRegistryBinding.isTrusted`.
+ *   3. Image — probe via `ImageRegistryBinding.head`, verify digest in
+ *      the image ref matches the descriptor; extract `/app/index.json`,
+ *      verify its sha256 matches the signed `indexHash` and its
+ *      `artifactVersion` is the signed one.
+ *   4. Manifest validation — the image's `/app/index.json` (not a copy
+ *      from the request: only the image's bytes are signed). Each
+ *      `tools[]`, `guardrails[]`, `agents[]`, `flows[]` runs through its
+ *      validator. A tool's `modulePath` and a
+ *      guardrail's `checkModulePath` become `codeArtifactRef: { kind:
+ *      'oci', imageRef, modulePath, artifactVersion }`, which is how the
+ *      runtime knows the code runs in the pack service; a guardrail's
+ *      `checkId` becomes its `check`. Agents and flows are declarative:
+ *      their `modulePath` is dropped.
+ *   5. Upserts — tools + guardrails + agents + flows. Track which were
+ *      `ok` (newly registered) vs `already-registered` so rollback only
+ *      unwinds our own writes.
+ *   6. Deployment record via `DeploymentBinding.register`. On failure,
+ *      rollback all `ok` upserts and return 500.
+ *
+ * ### Idempotency
+ *
+ * Two layers:
+ *   - `Idempotency-Key` middleware caches the full HTTP response — a
+ *     retry with the same key + same body replays the original 201.
+ *   - Digest idempotency handled inside `DeploymentBinding.register`:
+ *     the same `imageDigest` re-submitted under the same tenant returns
+ *     `{ kind: 'already-registered', deployment }` and the route surfaces
+ *     it as `200` (NOT `201`), same `deploymentId` + `artifactVersion`.
+ *
+ * ### Immutable records
+ *
+ * No PATCH, no DELETE. Each record lists exactly what it shipped
+ * (`contents`: ids and versions). Versions are immutable and an image
+ * digest deploys once, so the latest deployment is the live one, and a
+ * rollback rolls forward: deploy the earlier code again, under new
+ * versions. (Re-activating an earlier record instead would need every
+ * resolver to resolve only within the active deployment's versions.)
+ *
+ * The route is register-only + read-only.
+ */
+export interface DeploymentsRouterBindings {
+    readonly deploymentRegistry: DeploymentBinding;
+    readonly signingKeyRegistry: SigningKeyRegistryBinding;
+    readonly imageRegistry: ImageRegistryBinding;
+    readonly toolRegistry?: ToolRegistryBinding;
+    readonly guardrailRegistry?: GuardrailRegistryBinding;
+    readonly agentRegistry?: AgentRegistryBinding;
+    readonly flowRegistry?: FlowRegistryBinding;
+    /**
+     * REQUIRED at runtime for `POST /v1/deployments/:deploymentId/secrets`.
+     * Optional at the type level so app compositions without a secrets
+     * binding keep booting — the sync route is always mounted and answers
+     * `500` when this is not wired; the register / list / get routes remain
+     * functional without it.
+     */
+    readonly secretsBinding?: SecretBinding;
+    /**
+     * OPTIONAL at the type level, but REQUIRED at runtime any time
+     * `validated.agents.length > 0` OR `validated.flows.length > 0`
+     * OR `validated.tools.length > 0` OR `validated.guardrails.length > 0`.
+     * The agent / flow / tool / guardrail register loops resolve the
+     * tenant's Default project via `projectBinding.getDefault(tenantId)`
+     * and thread the resolved id through
+     * `AgentRegistryBinding.publish(...)` /
+     * `FlowRegistryBinding.publish(...)` /
+     * `ToolRegistryBinding.register(...)` /
+     * `GuardrailRegistryBinding.register(...)` (content-scoped writes
+     * always carry a project; deploys target the Default project).
+     * A deployment that carries any of those primitives without this
+     * binding wired fails fast at the loop entrypoint with a clear 500
+     * message. All four register loops resolve the project the same way.
+     */
+    readonly projectBinding?: ProjectBinding;
+    /**
+     * Called for each tool and guardrail a new deployment registered, as
+     * `POST /v1/tools` and `POST /v1/guardrails` call them, so a runtime
+     * that caches the catalogs (its tool and guardrail bridges) sees the
+     * deployment at once rather than at restart. Advisory: a failing hook
+     * doesn't fail the deployment.
+     */
+    readonly onToolWrite?: ToolWriteHook;
+    readonly onGuardrailWrite?: GuardrailWriteHook;
+}
+export declare function deploymentsRouter(bindings: DeploymentsRouterBindings): Hono<AppEnv>;
+export declare function sha256HexPrefixed(bytes: Uint8Array): string;
+//# sourceMappingURL=deployments.d.ts.map

package/dist/routes/deployments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployments.d.ts","sourceRoot":"","sources":["../../src/routes/deployments.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,cAAc,EAAS,MAAM,kBAAkB,CAAC;AAY9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EAEV,iBAAiB,EAGlB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,iBAAiB,IAAI,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,kBAAkB,EAAE,iBAAiB,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,yBAAyB,CAAC;IACvD,QAAQ,CAAC,aAAa,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,wBAAwB,CAAC;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,aAAa,CAAC;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,CAAC;IACzC;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC;CAChD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI,CAAC,MAAM,CAAC,CAgzBnF;AA2gBD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAG3D"}