@kindgi/api 0.0.0-bootstrap.0 → 0.1.0

package/dist/routes/schedules.js

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { Hono } from 'hono';
+import { statusFor, toWireError } from '../errors.js';
+import { clampLimit } from './pagination.js';
+/**
+ * Schedules — cron-kind triggers.
+ *
+ * Seven routes, all soft-delete-shaped per framework convention:
+ *   - POST   /v1/schedules                 (register)
+ *   - GET    /v1/schedules                 (list, cursor-paginated)
+ *   - GET    /v1/schedules/:triggerId      (get)
+ *   - PATCH  /v1/schedules/:triggerId      (update cron/label/flowVersion)
+ *   - POST   /v1/schedules/:triggerId/pause
+ *   - POST   /v1/schedules/:triggerId/resume
+ *   - POST   /v1/schedules/:triggerId/unregister  (tombstone — GC per policy)
+ *
+ * The `triggerId` URL param is the trigger's id; the response body
+ * aliases it as `scheduleId` for a friendlier client surface.
+ */
+export function schedulesRouter(binding) {
+    const r = new Hono();
+    // ---------- POST / (register) ----------
+    r.post('/', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const parsed = await parseJsonObject(c, requestId);
+        if (parsed.kind === 'err')
+            return parsed.response;
+        const body = parsed.value;
+        const flowId = requireString(body, 'flowId');
+        const flowVersion = requireString(body, 'flowVersion');
+        const cronExpression = requireString(body.config, 'config.cronExpression');
+        if (flowId.kind === 'err')
+            return bad(c, requestId, flowId.message);
+        if (flowVersion.kind === 'err')
+            return bad(c, requestId, flowVersion.message);
+        if (cronExpression.kind === 'err')
+            return bad(c, requestId, cronExpression.message);
+        const rawConfig = (body.config ?? {});
+        const registerInput = {
+            kind: 'cron',
+            tenantId,
+            flowId: flowId.value,
+            flowVersion: flowVersion.value,
+            config: {
+                cronExpression: cronExpression.value,
+                ...(typeof rawConfig.timezone === 'string' && { timezone: rawConfig.timezone }),
+                ...('input' in rawConfig && { input: rawConfig.input }),
+            },
+            ...(typeof body.label === 'string' && body.label.length > 0 && { label: body.label }),
+        };
+        const result = await binding.register(registerInput);
+        if (result.kind === 'err') {
+            c.status(statusFor(result.error.code));
+            return c.json(toWireError({ code: result.error.code, message: result.error.message }, requestId));
+        }
+        c.status(201);
+        return c.json(serializeSchedule(result.value));
+    });
+    // ---------- GET / (list) ----------
+    r.get('/', async (c) => {
+        const tenantId = c.get('tenantId');
+        const limit = clampLimit(c.req.query('limit'));
+        const cursorRaw = c.req.query('cursor');
+        const statusRaw = c.req.query('status');
+        let statusFilter;
+        if (statusRaw === 'active' || statusRaw === 'paused')
+            statusFilter = statusRaw;
+        const page = await binding.list({
+            tenantId,
+            kind: 'cron',
+            limit,
+            ...(cursorRaw !== undefined && cursorRaw.length > 0 && { cursor: cursorRaw }),
+            ...(statusFilter !== undefined && { status: statusFilter }),
+        });
+        return c.json({
+            data: page.data.map((row) => serializeSchedule(row)),
+            hasMore: page.nextCursor !== undefined,
+            ...(page.nextCursor !== undefined && { nextCursor: page.nextCursor }),
+        });
+    });
+    // ---------- GET /:triggerId (get) ----------
+    r.get('/:triggerId', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const triggerId = c.req.param('triggerId');
+        const rec = await binding.get({ tenantId, triggerId });
+        if (rec === null || rec.kind !== 'cron')
+            return notFound(c, requestId, triggerId);
+        return c.json(serializeSchedule(rec));
+    });
+    // ---------- PATCH /:triggerId (update) ----------
+    r.patch('/:triggerId', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const triggerId = c.req.param('triggerId');
+        const parsed = await parseJsonObject(c, requestId);
+        if (parsed.kind === 'err')
+            return parsed.response;
+        const body = parsed.value;
+        const patchConfig = body.config;
+        const cfg = {};
+        if (patchConfig !== undefined) {
+            if (typeof patchConfig.cronExpression === 'string')
+                cfg.cronExpression = patchConfig.cronExpression;
+            if (typeof patchConfig.timezone === 'string')
+                cfg.timezone = patchConfig.timezone;
+            if ('input' in patchConfig)
+                cfg.input = patchConfig.input;
+        }
+        const updateInput = {
+            kind: 'cron',
+            tenantId,
+            triggerId,
+            ...(Object.keys(cfg).length > 0 && { config: cfg }),
+            ...('label' in body && { label: body.label === null ? null : body.label }),
+            ...(typeof body.flowVersion === 'string' && { flowVersion: body.flowVersion }),
+        };
+        const result = await binding.update(updateInput);
+        if (result.kind === 'err') {
+            c.status(statusFor(result.error.code));
+            return c.json(toWireError({
+                code: result.error.code,
+                message: result.error.message,
+                triggerId: triggerId,
+            }, requestId));
+        }
+        return c.json(serializeSchedule(result.value));
+    });
+    // ---------- POST /:triggerId/pause ----------
+    r.post('/:triggerId/pause', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const triggerId = c.req.param('triggerId');
+        const result = await binding.pause({ tenantId, triggerId });
+        if (result.kind === 'err')
+            return lifecycleError(c, requestId, result.error, triggerId);
+        return c.json(serializeSchedule(result.value));
+    });
+    // ---------- POST /:triggerId/resume ----------
+    r.post('/:triggerId/resume', async (c) => {
+        const requestId = c.get('requestId');
+        const tenantId = c.get('tenantId');
+        const triggerId = c.req.param('triggerId');
+        const result = await binding.resume({ tenantId, triggerId });
+        if (result.kind === 'err')
+            return lifecycleError(c, requestId, result.error, triggerId);
+        return c.json(serializeSchedule(result.value));
+    });
+    // ---------- POST /:triggerId/unregister (soft delete) ----------
+    r.post('/:triggerId/unregister', async (c) => {
+        const tenantId = c.get('tenantId');
+        const triggerId = c.req.param('triggerId');
+        const outcome = await binding.unregister({ tenantId, triggerId });
+        return c.json({
+            scheduleId: triggerId,
+            unregistered: outcome.unregistered,
+        });
+    });
+    return r;
+}
+// -----------------------------------------------------------------------
+// Shared helpers (co-located to keep each router self-contained).
+// -----------------------------------------------------------------------
+function serializeSchedule(r) {
+    return {
+        scheduleId: r.triggerId,
+        triggerId: r.triggerId,
+        flowId: r.flowId,
+        flowVersion: r.flowVersion,
+        cronExpression: r.config.cronExpression,
+        ...(r.config.timezone !== undefined && { timezone: r.config.timezone }),
+        ...(r.config.input !== undefined && { input: r.config.input }),
+        label: r.label,
+        status: r.status,
+        nextFireAt: r.nextFireAt,
+        lastFiredAt: r.lastFiredAt,
+        createdAt: r.createdAt,
+        updatedAt: r.updatedAt,
+    };
+}
+async function parseJsonObject(c, requestId) {
+    let body;
+    try {
+        body = await c.req.json();
+    }
+    catch {
+        c.status(statusFor('bad-input'));
+        return {
+            kind: 'err',
+            response: c.json(toWireError({ code: 'bad-input', message: 'Request body must be valid JSON' }, requestId)),
+        };
+    }
+    if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        c.status(statusFor('bad-input'));
+        return {
+            kind: 'err',
+            response: c.json(toWireError({ code: 'bad-input', message: 'Request body must be a JSON object' }, requestId)),
+        };
+    }
+    return { kind: 'ok', value: body };
+}
+function requireString(obj, path) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (const part of parts) {
+        if (cur === null || typeof cur !== 'object') {
+            return { kind: 'err', message: `\`${path}\` is required` };
+        }
+        cur = cur[part];
+    }
+    if (typeof cur !== 'string' || cur.length === 0) {
+        return { kind: 'err', message: `\`${path}\` is required` };
+    }
+    return { kind: 'ok', value: cur };
+}
+function bad(c, requestId, message) {
+    c.status(statusFor('bad-input'));
+    return c.json(toWireError({ code: 'bad-input', message }, requestId));
+}
+function notFound(c, requestId, triggerId) {
+    c.status(statusFor('trigger-not-found'));
+    return c.json(toWireError({
+        code: 'trigger-not-found',
+        message: `No trigger with id "${triggerId}"`,
+        triggerId: triggerId,
+    }, requestId));
+}
+function lifecycleError(c, requestId, error, triggerId) {
+    c.status(statusFor(error.code));
+    return c.json(toWireError({ code: error.code, message: error.message, triggerId: triggerId }, requestId));
+}
+//# sourceMappingURL=schedules.js.map

package/dist/routes/schedules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedules.js","sourceRoot":"","sources":["../../src/routes/schedules.ts"],"names":[],"mappings":"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"}

package/dist/routes/scope-params.d.ts

@@ -0,0 +1,57 @@
+import { type ResourceRef } from '@kindgi/authz';
+import type { Scope } from '@kindgi/platform';
+import type { TenantId } from '@kindgi/types';
+/**
+ * The authorization resource for a request scope: the project or org it
+ * names, else the tenant. A route's authorization middleware derives the
+ * scope with the same parser as its handler and passes the result here, so
+ * the scope that is checked is the scope that is acted on. An absent or
+ * unparseable scope checks the tenant, the strictest resource; the handler
+ * then rejects the request.
+ */
+export declare function scopeResourceRef(scope: Scope | undefined, tenantId: TenantId): ResourceRef;
+/** {@link scopeResourceRef} for the `?scopeKind` + `?scopeId` query parameters. */
+export declare function queryScopeResourceRef(query: QuerySource, session: {
+    readonly tenantId: TenantId;
+}): ResourceRef;
+/**
+ * Outcome of parsing the `?scopeKind + ?scopeId + ?inherit` triplet.
+ * `ok` carries the decoded `Scope` (undefined if no scope params were
+ * supplied) plus the parsed `inherit` boolean (undefined if elided —
+ * caller leaves the binding to apply its own default).
+ */
+export type ParseScopeParamsOutcome = {
+    readonly kind: 'ok';
+    readonly scope?: Scope;
+    readonly inherit?: boolean;
+} | {
+    readonly kind: 'err';
+    readonly message: string;
+};
+type QuerySource = Record<string, string> | ((name: string) => string | undefined);
+/**
+ * Parse the `?scopeKind + ?scopeId + ?inherit` triplet. The wire shape
+ * is a discriminated triplet by design — human-readable, curl / browser
+ * / access-log auditable for regulated verticals.
+ *
+ * Cross-field validation (all return 400 `scope-invalid`):
+ * - `scopeKind === 'tenant' && scopeId !== undefined` → err (tenant carries no id).
+ * - `scopeKind in {'org','project'} && scopeId === undefined` → err (missing id).
+ * - `scopeKind === undefined && scopeId !== undefined` → err (orphan id).
+ * - `inherit` — accepts literal 'true' / 'false' strings; anything else → err.
+ *
+ * `tenantId` for the decoded Scope always comes from the session —
+ * cross-tenant scopes are denied by policy.
+ *
+ * `inherit` is load-bearing for policy/config-scoped bindings
+ * (e.g. MCP endpoints, secrets, env values) — controls the
+ * upward-hierarchy walk. For content-scoped bindings the flag is a
+ * documented no-op; the route passes it through so the binding-side
+ * field-passthrough shape stays uniform across the scope-aware
+ * bindings.
+ */
+export declare function parseScopeParams(query: QuerySource, session: {
+    readonly tenantId: TenantId;
+}): ParseScopeParamsOutcome;
+export {};
+//# sourceMappingURL=scope-params.d.ts.map

package/dist/routes/scope-params.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-params.d.ts","sourceRoot":"","sources":["../../src/routes/scope-params.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,WAAW,EAAO,MAAM,eAAe,CAAC;AACtD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,KAAK,EAAoB,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,EAAE,QAAQ,EAAE,QAAQ,GAAG,WAAW,CAI1F;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACvC,WAAW,CAGb;AAED;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,KAAK,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;AAEnF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,WAAW,EAClB,OAAO,EAAE;IAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,GACvC,uBAAuB,CAkEzB"}

package/dist/routes/scope-params.js

@@ -0,0 +1,105 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { ref } from '@kindgi/authz';
+/**
+ * The authorization resource for a request scope: the project or org it
+ * names, else the tenant. A route's authorization middleware derives the
+ * scope with the same parser as its handler and passes the result here, so
+ * the scope that is checked is the scope that is acted on. An absent or
+ * unparseable scope checks the tenant, the strictest resource; the handler
+ * then rejects the request.
+ */
+export function scopeResourceRef(scope, tenantId) {
+    if (scope?.kind === 'project')
+        return ref('project', scope.projectId);
+    if (scope?.kind === 'org')
+        return ref('org', scope.orgId);
+    return ref('tenant', tenantId);
+}
+/** {@link scopeResourceRef} for the `?scopeKind` + `?scopeId` query parameters. */
+export function queryScopeResourceRef(query, session) {
+    const parsed = parseScopeParams(query, session);
+    return scopeResourceRef(parsed.kind === 'ok' ? parsed.scope : undefined, session.tenantId);
+}
+/**
+ * Parse the `?scopeKind + ?scopeId + ?inherit` triplet. The wire shape
+ * is a discriminated triplet by design — human-readable, curl / browser
+ * / access-log auditable for regulated verticals.
+ *
+ * Cross-field validation (all return 400 `scope-invalid`):
+ * - `scopeKind === 'tenant' && scopeId !== undefined` → err (tenant carries no id).
+ * - `scopeKind in {'org','project'} && scopeId === undefined` → err (missing id).
+ * - `scopeKind === undefined && scopeId !== undefined` → err (orphan id).
+ * - `inherit` — accepts literal 'true' / 'false' strings; anything else → err.
+ *
+ * `tenantId` for the decoded Scope always comes from the session —
+ * cross-tenant scopes are denied by policy.
+ *
+ * `inherit` is load-bearing for policy/config-scoped bindings
+ * (e.g. MCP endpoints, secrets, env values) — controls the
+ * upward-hierarchy walk. For content-scoped bindings the flag is a
+ * documented no-op; the route passes it through so the binding-side
+ * field-passthrough shape stays uniform across the scope-aware
+ * bindings.
+ */
+export function parseScopeParams(query, session) {
+    const get = typeof query === 'function' ? query : (n) => query[n];
+    const scopeKindRaw = get('scopeKind');
+    const scopeIdRaw = get('scopeId');
+    const inheritRaw = get('inherit');
+    // ---- inherit ----
+    let inherit;
+    if (inheritRaw !== undefined && inheritRaw.length > 0) {
+        if (inheritRaw === 'true')
+            inherit = true;
+        else if (inheritRaw === 'false')
+            inherit = false;
+        else {
+            return {
+                kind: 'err',
+                message: `scope query parameters malformed: inherit must be 'true' or 'false', got "${inheritRaw}"`,
+            };
+        }
+    }
+    // ---- scope triplet ----
+    if (scopeKindRaw === undefined || scopeKindRaw.length === 0) {
+        if (scopeIdRaw !== undefined && scopeIdRaw.length > 0) {
+            return {
+                kind: 'err',
+                message: `scope query parameters malformed: scopeId="${scopeIdRaw}" requires scopeKind`,
+            };
+        }
+        return { kind: 'ok', ...(inherit !== undefined && { inherit }) };
+    }
+    if (scopeKindRaw !== 'tenant' && scopeKindRaw !== 'org' && scopeKindRaw !== 'project') {
+        return {
+            kind: 'err',
+            message: `scope query parameters malformed: scopeKind must be one of 'tenant' | 'org' | 'project', got "${scopeKindRaw}"`,
+        };
+    }
+    if (scopeKindRaw === 'tenant') {
+        if (scopeIdRaw !== undefined && scopeIdRaw.length > 0) {
+            return {
+                kind: 'err',
+                message: `scope query parameters malformed: scopeKind='tenant' takes no scopeId (tenant is implicit from the session)`,
+            };
+        }
+        return {
+            kind: 'ok',
+            scope: { kind: 'tenant', tenantId: session.tenantId },
+            ...(inherit !== undefined && { inherit }),
+        };
+    }
+    // 'org' | 'project' — both require scopeId
+    if (scopeIdRaw === undefined || scopeIdRaw.length === 0) {
+        return {
+            kind: 'err',
+            message: `scope query parameters malformed: scopeKind='${scopeKindRaw}' requires scopeId`,
+        };
+    }
+    const scope = scopeKindRaw === 'org'
+        ? { kind: 'org', tenantId: session.tenantId, orgId: scopeIdRaw }
+        : { kind: 'project', tenantId: session.tenantId, projectId: scopeIdRaw };
+    return { kind: 'ok', scope, ...(inherit !== undefined && { inherit }) };
+}
+//# sourceMappingURL=scope-params.js.map

package/dist/routes/scope-params.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-params.js","sourceRoot":"","sources":["../../src/routes/scope-params.ts"],"names":[],"mappings":"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"}

package/dist/routes/secret-ref.d.ts

@@ -0,0 +1,20 @@
+import { type EnvName } from '@kindgi/types';
+/** The longest secret name a `secretRef` can carry. */
+export declare const MAX_SECRET_NAME_LENGTH = 256;
+/**
+ * `{ envName, name }`: a secret by name in the deployment's secrets
+ * store, resolved at the owner's scope. The shape webhooks, MCP
+ * endpoints and providers share. `field` names it in messages.
+ */
+export declare function parseSecretRef(raw: unknown, field?: string): {
+    readonly kind: 'ok';
+    readonly value: {
+        readonly envName: EnvName;
+        readonly name: string;
+    };
+} | {
+    readonly kind: 'err';
+    readonly message: string;
+    readonly unknownField?: string;
+};
+//# sourceMappingURL=secret-ref.d.ts.map

package/dist/routes/secret-ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-ref.d.ts","sourceRoot":"","sources":["../../src/routes/secret-ref.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,OAAO,EAAe,MAAM,eAAe,CAAC;AAE1D,uDAAuD;AACvD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAI1C;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,OAAO,EACZ,KAAK,SAAc,GAEjB;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAC7F;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CA+BrF"}

package/dist/routes/secret-ref.js

@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+import { makeEnvName } from '@kindgi/types';
+/** The longest secret name a `secretRef` can carry. */
+export const MAX_SECRET_NAME_LENGTH = 256;
+const SECRET_REF_FIELDS = new Set(['envName', 'name']);
+/**
+ * `{ envName, name }`: a secret by name in the deployment's secrets
+ * store, resolved at the owner's scope. The shape webhooks, MCP
+ * endpoints and providers share. `field` names it in messages.
+ */
+export function parseSecretRef(raw, field = 'secretRef') {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { kind: 'err', message: `\`${field}\` must be an object \`{ envName, name }\`` };
+    }
+    const ref = raw;
+    const unknown = Object.keys(ref).find((key) => !SECRET_REF_FIELDS.has(key));
+    if (unknown !== undefined) {
+        return {
+            kind: 'err',
+            message: `Unknown field \`${field}.${unknown}\``,
+            unknownField: `${field}.${unknown}`,
+        };
+    }
+    const envName = typeof ref.envName === 'string' ? makeEnvName(ref.envName) : null;
+    if (envName === null) {
+        return {
+            kind: 'err',
+            message: `\`${field}.envName\` must be a lowercase name (letters, digits, hyphens)`,
+        };
+    }
+    if (typeof ref.name !== 'string' ||
+        ref.name.length === 0 ||
+        ref.name.length > MAX_SECRET_NAME_LENGTH) {
+        return {
+            kind: 'err',
+            message: `\`${field}.name\` must be a non-empty string of at most ${MAX_SECRET_NAME_LENGTH} characters`,
+        };
+    }
+    return { kind: 'ok', value: { envName, name: ref.name } };
+}
+//# sourceMappingURL=secret-ref.js.map

package/dist/routes/secret-ref.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-ref.js","sourceRoot":"","sources":["../../src/routes/secret-ref.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAEjC,OAAO,EAAgB,WAAW,EAAE,MAAM,eAAe,CAAC;AAE1D,uDAAuD;AACvD,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAC;AAE1C,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAY,EACZ,KAAK,GAAG,WAAW;IAInB,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,KAAK,4CAA4C,EAAE,CAAC;IAC1F,CAAC;IACD,MAAM,GAAG,GAAG,GAA8B,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,mBAAmB,KAAK,IAAI,OAAO,IAAI;YAChD,YAAY,EAAE,GAAG,KAAK,IAAI,OAAO,EAAE;SACpC,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,KAAK,KAAK,gEAAgE;SACpF,CAAC;IACJ,CAAC;IACD,IACE,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;QAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,sBAAsB,EACxC,CAAC;QACD,OAAO;YACL,IAAI,EAAE,KAAK;YACX,OAAO,EAAE,KAAK,KAAK,iDAAiD,sBAAsB,aAAa;SACxG,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;AAC5D,CAAC"}

package/dist/routes/secrets.d.ts

@@ -0,0 +1,53 @@
+import { Hono } from 'hono';
+import type { Authorizer } from '../middleware/authorize.js';
+import type { RotationStatusStore } from '../rotation-status-store.js';
+import type { SecretBinding } from '../secrets-binding.js';
+import type { AppEnv } from '../types.js';
+/**
+ * `/v1/secrets/*` — HTTP surface for `SecretBinding`. Nine endpoints
+ * covering the full
+ * lifecycle: list / get / set / rotate (sync + async) / rotation-status
+ * poll / rotation-status SSE / revoke / version list / version get.
+ *
+ * Wire-safety:
+ *   - `value` NEVER returns from list / get / getVersion / listVersions.
+ *   - Within `/v1/secrets`, plaintext is accepted only by `POST /`
+ *     (`value`, `secrets:write` capability) and `POST /:name/rotate`
+ *     (optional `newValue`, `secrets:rotate` capability).
+ *   - Async rotation returns 202 with `{ rotationId, statusUrl,
+ *     eventsUrl }`; sync rotation returns 201 with the outcome inline.
+ *
+ * Capability gates:
+ *   - `secrets:write`   → POST /
+ *   - `secrets:rotate`  → POST /:name/rotate
+ *   - `secrets:revoke`  → DELETE /:name (soft)
+ *   - `secrets:revoke:hard` → DELETE /:name?hard=true
+ *   - `secrets:reveal`  → not used by these routes; there is no HTTP
+ *     `resolve` path.
+ *
+ * SSE:
+ *   - `GET /:name/rotations/:rotationId/events` streams
+ *     `event: rotation-update\ndata: <json>\n\n` frames on each status
+ *     change. An `event: ping` heartbeat (empty data) every 15s keeps
+ *     proxies from timing the stream out; the stream closes on terminal
+ *     state.
+ */
+export interface SecretsRouterOptions {
+    readonly secretsBinding: SecretBinding;
+    readonly rotationStatusStore: RotationStatusStore;
+    /**
+     * Overrideable SSE heartbeat interval. Default 15_000 ms; tests
+     * pass a low value to keep suites fast.
+     */
+    readonly sseHeartbeatMs?: number;
+    /**
+     * Optional fine-grained authorizer. When present, gates every route
+     * on `admin` on the request's `scope` (query for GET/DELETE, body for
+     * create, body or query for rotate). Reads are STRICT: strict-read means `admin from scope`
+     * or explicit `reader` grant — cascade via the scope tuple written
+     * by `secretsBinding.set` on fresh create.
+     */
+    readonly authorizer?: Authorizer;
+}
+export declare function secretsRouter(options: SecretsRouterOptions): Hono<AppEnv>;
+//# sourceMappingURL=secrets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../../src/routes/secrets.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,KAAK,EAAkB,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvF,OAAO,KAAK,EACV,aAAa,EAId,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAK1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,aAAa,CAAC;IACvC,QAAQ,CAAC,mBAAmB,EAAE,mBAAmB,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;CAClC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC,MAAM,CAAC,CA4uBzE"}