@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/delivery-token.d.ts

@@ -0,0 +1,41 @@
+import type { AuthScope, TenantContext } from "./context.js";
+/** What a delivery token is for: one delivery of an Action, or a ping. */
+export type DeliveryTokenFor = {
+    kind: "action";
+    actionId: string;
+    agentId: string;
+    generation: number;
+} | {
+    kind: "ping";
+    agentId: string;
+};
+export interface MintedDeliveryToken {
+    token: string;
+    /** Milliseconds since the epoch. */
+    expiresAt: number;
+    tokenId: string;
+    keyId: string;
+}
+/** The request scope of a verified delivery token (`AuthScope` kind `delivery`). */
+export type DeliveryScope = Extract<AuthScope, {
+    kind: "delivery";
+}>;
+/** base64url SHA-256 of a request body: the token's `bdy` claim. */
+export declare function bodyHash(body: string | Uint8Array): string;
+/**
+ * Signs a token for `delivery`, for the endpoint at `audience`, covering `body`. `ttlSeconds`
+ * is capped at `DELIVERY_TOKEN_MAX_TTL_SECONDS`.
+ */
+export declare function mintDeliveryToken(ctx: TenantContext, options: {
+    for: DeliveryTokenFor;
+    audience: string;
+    body: string | Uint8Array;
+    ttlSeconds: number;
+}): Promise<MintedDeliveryToken>;
+/**
+ * Verifies a delivery token presented as a bearer. Answers `401 token_expired` for an expired
+ * token or a revoked key, and the opaque 404 for everything else, a ping token included: only
+ * an Action's token reaches its callbacks. Whether the Action is still being delivered at the
+ * token's generation is checked where the Action is read (`auth.ts` `scoped`).
+ */
+export declare function verifyDeliveryToken(ctx: TenantContext, raw: string): Promise<DeliveryScope>;

package/dist/tenant/delivery-token.js

@@ -0,0 +1,104 @@
+/**
+ * Delivery tokens (design: Action endpoints §8.1): the ES256 JWT the Runtime signs, with the
+ * Tenant's current signing key, for one delivery of one Action, or for a ping. It travels in
+ * `Nylorun-Signature` on the request to the Action endpoint, which verifies it with the
+ * Tenant's public keys, and comes back as the bearer of that Action's callbacks (a background
+ * result, heartbeats, sandbox tools).
+ *
+ * A token lives at most `DELIVERY_TOKEN_MAX_TTL_SECONDS`, the subject-token maximum, and key
+ * rotation waits at least that long before it revokes the previous key
+ * (`signing-keys.ts`), so a rotation never revokes a live token.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { errors, jwtVerify } from "jose";
+import { DELIVERY_TOKEN_MAX_TTL_SECONDS, DELIVERY_TOKEN_TYPE, subjectTokenIssuer, } from "@nylorun/core/contracts";
+import { failOpaque, HttpError } from "./http.js";
+import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "./jwt.js";
+/** base64url SHA-256 of a request body: the token's `bdy` claim. */
+export function bodyHash(body) {
+    return createHash("sha256").update(body).digest("base64url");
+}
+/**
+ * Signs a token for `delivery`, for the endpoint at `audience`, covering `body`. `ttlSeconds`
+ * is capped at `DELIVERY_TOKEN_MAX_TTL_SECONDS`.
+ */
+export async function mintDeliveryToken(ctx, options) {
+    const ttl = Math.max(1, Math.min(Math.floor(options.ttlSeconds), DELIVERY_TOKEN_MAX_TTL_SECONDS));
+    const iat = Math.floor(Date.now() / 1000);
+    const tokenId = randomUUID();
+    const delivery = options.for;
+    // Signed by the keys service (F4.2): this process never holds the private key.
+    const { token, keyId } = await ctx.keys.sign({
+        typ: DELIVERY_TOKEN_TYPE,
+        claims: {
+            agt: delivery.agentId,
+            gen: delivery.kind === "action" ? delivery.generation : 0,
+            bdy: bodyHash(options.body),
+            iss: subjectTokenIssuer(ctx.config.tenantId),
+            aud: options.audience,
+            sub: delivery.kind === "action" ? delivery.actionId : "ping",
+            iat,
+            exp: iat + ttl,
+            jti: tokenId,
+        },
+    });
+    return { token, expiresAt: (iat + ttl) * 1000, tokenId, keyId };
+}
+/**
+ * Verifies a delivery token presented as a bearer. Answers `401 token_expired` for an expired
+ * token or a revoked key, and the opaque 404 for everything else, a ping token included: only
+ * an Action's token reaches its callbacks. Whether the Action is still being delivered at the
+ * token's generation is checked where the Action is read (`auth.ts` `scoped`).
+ */
+export async function verifyDeliveryToken(ctx, raw) {
+    const checked = tokenKeyId(raw, DELIVERY_TOKEN_TYPE);
+    if ("refused" in checked)
+        return refused(ctx, `delivery_token_${checked.refused}`);
+    const { kid } = checked;
+    const row = await ctx.store.tx((t) => t.signingKey(kid));
+    if (!row)
+        return refused(ctx, "delivery_token_key_unknown");
+    let claims;
+    try {
+        const verified = await jwtVerify(raw, await ctx.signingKeys.publicKey(row), {
+            algorithms: ["ES256"],
+            issuer: subjectTokenIssuer(ctx.config.tenantId),
+            typ: DELIVERY_TOKEN_TYPE,
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+            requiredClaims: ["sub", "aud", "iat", "exp", "jti"],
+        });
+        claims = verified.payload;
+    }
+    catch (error) {
+        if (error instanceof errors.JWTExpired)
+            expired(ctx, "delivery_token_expired");
+        return refused(ctx, "delivery_token_invalid");
+    }
+    if (row.state === "revoked")
+        expired(ctx, "delivery_token_key_revoked");
+    const { sub, agt, gen, exp, iat, jti } = claims;
+    if (sub === "ping" ||
+        typeof agt !== "string" ||
+        typeof gen !== "number" ||
+        !Number.isInteger(gen) ||
+        gen < 1 ||
+        exp - iat > DELIVERY_TOKEN_MAX_TTL_SECONDS)
+        return refused(ctx, "delivery_token_claims");
+    return {
+        kind: "delivery",
+        actionId: sub,
+        agentId: agt,
+        generation: gen,
+        expiresAt: exp * 1000,
+        tokenId: jti,
+        keyId: kid,
+    };
+}
+function refused(ctx, reason) {
+    ctx.config.logger.warn("credential rejected", { reason });
+    return failOpaque();
+}
+function expired(ctx, reason) {
+    ctx.config.logger.warn("delivery token refused", { reason });
+    throw new HttpError(401, "The delivery token has expired or its key was revoked", { code: "token_expired" }, { "www-authenticate": 'Bearer error="invalid_token"' });
+}

package/dist/tenant/delivery.d.ts

@@ -0,0 +1,62 @@
+import { type Action, type ActionOutcome, type DeliveryHeartbeatResponse, type EndpointPingResponse } from "@nylorun/core/contracts";
+import type { DeliverResult } from "../execution/types.js";
+import type { Tx } from "../store/types.js";
+import { type Session, type TenantContext } from "./context.js";
+import { type DeliveryScope } from "./delivery-token.js";
+import type { OutboundResult } from "./outbound.js";
+/**
+ * Offers an Action that just became `pending` to its agent's endpoint, after the transaction
+ * commits. Without an endpoint it waits for the agent's next registration (`PUT /v1/endpoints`).
+ */
+export declare function offerAction(t: Tx, ctx: Pick<TenantContext, "deliver">, action: Pick<Action, "actionId" | "agentId">): Promise<void>;
+/** Delivers one Action (`WorkerHandlers.deliver`). Throws only on infrastructure errors. */
+export declare function deliverAction(ctx: TenantContext, actionId: string, signal: AbortSignal): Promise<DeliverResult>;
+type Settlement = {
+    kind: "outcome";
+    outcome: ActionOutcome;
+} | {
+    kind: "accepted";
+} | {
+    kind: "retry";
+    code: string;
+    message: string;
+    retryAfterMs?: number;
+} | {
+    kind: "lost";
+    code: string;
+    message: string;
+};
+/** What an endpoint's answer means for the Action (design §5.2, §5.3). */
+export declare function interpret(action: Action, result: OutboundResult): Settlement;
+/**
+ * A delivery that may have reached the endpoint got no answer. A tool becomes `uncertain`, with
+ * its effect and its session. A hook,
+ * `fn` or `verify` is pure or repeat-safe and goes back to `pending`: delivered again right away
+ * (`after-commit`) or by the caller's retry (`retry`). Returns true when it will be delivered again.
+ */
+export declare function loseAction(t: Tx, ctx: Pick<TenantContext, "deliver">, s: Session, action: Action, options: {
+    redeliver: "after-commit" | "retry";
+}): Promise<boolean>;
+/**
+ * The sweep's part (design §7): deliveries whose deadline passed without an answer are lost,
+ * and pending Actions of agents with an endpoint are sent again, in case a send was lost
+ * between a commit and the execution. Returns how many deliveries it settled.
+ */
+export declare function sweepDeliveries(ctx: TenantContext, now?: Date): Promise<number>;
+/**
+ * `POST /v1/endpoints/:agentId/ping`: a signed ping through the endpoint, so a wrong URL, a
+ * tunnel that is down or a handler serving other definitions shows up before the first turn.
+ */
+export declare function pingEndpoint(ctx: TenantContext, agentId: string): Promise<EndpointPingResponse>;
+/**
+ * `POST /v1/actions/:id/heartbeat` with a delivery token: an endpoint that answered `202` keeps
+ * its delivery alive for another lease, and gets a fresh token for its next callbacks. `409`
+ * when the delivery was cancelled, lost or sent again, which tells the endpoint to stop.
+ */
+export declare function deliveryHeartbeat(ctx: TenantContext, scope: DeliveryScope, actionId: string): Promise<DeliveryHeartbeatResponse>;
+/**
+ * `POST /v1/actions/:id/result` with a delivery token: the outcome of a delivery answered with
+ * `202`. The same result again returns the first receipt; a different one is `409`.
+ */
+export declare function deliveryResult(ctx: TenantContext, scope: DeliveryScope, actionId: string, outcome: ActionOutcome): Promise<Record<string, unknown>>;
+export {};