@nylorun/runtime 0.16.0-beta → 0.19.0-beta

package/dist/api/http/routes/access.js

@@ -1,18 +1,12 @@
 import { z } from "zod";
-import { newPublishableKey, newPublishableKeyId } from "@nylorun/core/compatibility";
-import { CreatePublishableKeyRequestSchema, CreateTokenRequestSchema, PutAccessPolicyRequestSchema, RevokeSigningKeyRequestSchema, RevokeSubjectRequestSchema, RotateSigningKeysRequestSchema, UpdatePublishableKeyRequestSchema, } from "@nylorun/core/contracts";
-import { AccessPolicyResponse, CreatePublishableKeyRequest, CreateTokenRequest, CreateTokenResponse, Jwks, ListPublishableKeysResponse, PublishableKey, PutAccessPolicyRequest, RevokeSigningKeyRequest, RevokeSubjectRequest, RevokeSubjectResponse, RotateSigningKeysRequest, SigningKeyList, SigningKeyView, UpdatePublishableKeyRequest, } from "../../components.js";
-import { signalSubjectRevoked } from "../../../streams/control.js";
-import { readPolicy, writePolicy } from "../../../tenant/access-policy.js";
-import { currentBasin, endSubjectStreams } from "../../../tenant/session-streams.js";
-import { requireApplication } from "../../../tenant/auth.js";
-import { fail } from "../../../tenant/http.js";
+import { RevokeSigningKeyRequestSchema, RotateSigningKeysRequestSchema, TOKEN_TTL_MAX_SECONDS, } from "@nylorun/core/contracts";
+import { Jwks, RevokeSigningKeyRequest, RotateSigningKeysRequest, SigningKeyList, SigningKeyView, } from "../../components.js";
 import { publicJwk, signingKeyView } from "../../../tenant/signing-keys.js";
-import { mintToken } from "../../../tenant/tokens.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
-const APPLICATION = { credentials: ["application"], scopes: "never" };
+/** The Management API's signing-key routes: a management key. */
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
 const json = (schema, description) => ({
     description,
     content: { "application/json": { schema } },
@@ -21,21 +15,19 @@ const body = (schema) => ({
     required: true,
     content: { "application/json": { schema } },
 });
-const keyId = z.object({ keyId: z.string() });
 export function accessRoutes(api) {
     tenantRoute(api, {
-        credentials: ["application", "subject", "token", "publishable"],
+        credentials: ["application", "subject", "management", "token"],
         scopes: "any",
-        browser: true,
-        // Public keys: an Action endpoint verifies delivery tokens with them and holds no key.
+        // Public keys: a verifier of the Runtime's tokens holds no key.
         anonymous: true,
     }, {
         method: "get",
         path: "/v1/access/jwks",
         tags: ["Access"],
-        summary: "Get the public keys subject and delivery tokens are signed with",
-        description: "A JSON Web Key Set, to verify a subject token or a delivery token without calling the " +
-            "Runtime. No credential is needed.",
+        summary: "Get the public keys the Runtime's tokens are signed with",
+        description: "A JSON Web Key Set, to verify a token the Runtime signed without calling it. No " +
+            "credential is needed.",
         responses: { 200: json(Jwks, "The public keys") },
     }, async (c) => {
         // Anonymous: reads the public keys. Only when the current or standby key is missing does
@@ -49,49 +41,17 @@ export function accessRoutes(api) {
         }
         return jsonResponse(200, { keys: rows.map(publicJwk) });
     });
-    tenantRoute(api, APPLICATION, {
-        method: "post",
-        path: "/v1/tokens",
-        tags: ["Access"],
-        summary: "Mint a subject token",
-        description: "A token for one person and one role of the access policy, for their browser or app to call the Runtime with. At most 15 minutes.",
-        request: { body: body(CreateTokenRequest) },
-        responses: { 200: json(CreateTokenResponse, "The token, its scopes and expiry") },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        return jsonResponse(200, await mintToken(c.env.tenant, CreateTokenRequestSchema.parse(await readJson(c.req.raw))));
-    });
-    tenantRoute(api, APPLICATION, {
-        method: "get",
-        path: "/v1/access/policy",
-        tags: ["Access"],
-        summary: "Get the access policy",
-        responses: { 200: json(AccessPolicyResponse, "Roles, the anonymous grant and token lifetime") },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        return jsonResponse(200, { policy: await c.env.tenant.store.tx((t) => readPolicy(t)) });
-    });
-    tenantRoute(api, APPLICATION, {
-        method: "put",
-        path: "/v1/access/policy",
-        tags: ["Access"],
-        summary: "Set the access policy",
-        request: { body: body(PutAccessPolicyRequest) },
-        responses: { 200: json(AccessPolicyResponse, "The policy now in force") },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        const request = PutAccessPolicyRequestSchema.parse(await readJson(c.req.raw));
-        await c.env.tenant.store.tx((t) => writePolicy(t, request.policy));
-        return jsonResponse(200, { policy: request.policy });
-    });
-    tenantRoute(api, APPLICATION, {
+    signingKeyRoutesAt(api, "/v1/tenant/signing-keys", MANAGEMENT);
+}
+/** The signing-key routes under `base` (`/v1/tenant/signing-keys`). */
+function signingKeyRoutesAt(api, base, access) {
+    tenantRoute(api, access, {
         method: "get",
-        path: "/v1/access/signing-keys",
+        path: `${base}`,
         tags: ["Access"],
         summary: "List signing keys",
         responses: { 200: json(SigningKeyList, "Standby, current, previous and revoked keys") },
     }, async (c) => {
-        requireApplication(c.get("scope"));
         const ctx = c.env.tenant;
         const read = () => ctx.store.tx((t) => t.signingKeys());
         let rows = await read();
@@ -101,29 +61,31 @@ export function accessRoutes(api) {
         }
         return jsonResponse(200, { keys: rows.map(signingKeyView) });
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/access/signing-keys/rotate",
+        path: `${base}/rotate`,
         tags: ["Access"],
         summary: "Rotate the signing keys",
-        description: "The standby key signs from now on; the current one still verifies tokens it signed. `force` also ends every outstanding token.",
+        description: "The standby key signs from now on; the current one still verifies tokens it signed. `force` also ends every outstanding capability link and run token.",
         request: { body: body(RotateSigningKeysRequest) },
         responses: {
             200: json(SigningKeyList, "The keys after rotation"),
             409: { description: "The previous key may still verify outstanding tokens" },
         },
     }, async (c) => {
-        requireApplication(c.get("scope"));
         const ctx = c.env.tenant;
         const request = RotateSigningKeysRequestSchema.parse(await readJson(c.req.raw));
-        const maxTtlSeconds = await ctx.store.tx(async (t) => (await readPolicy(t)).tokens.maxTtlSeconds);
-        const keys = await ctx.keys.rotateSigningKeys({ maxTtlSeconds, force: request.force === true });
+        // The longest any token the Runtime signs lives (capability links, run tokens).
+        const keys = await ctx.keys.rotateSigningKeys({
+            maxTtlSeconds: TOKEN_TTL_MAX_SECONDS,
+            force: request.force === true,
+        });
         ctx.config.logger.info("signing keys rotated", { force: request.force === true });
         return jsonResponse(200, { keys });
     });
-    tenantRoute(api, APPLICATION, {
+    tenantRoute(api, access, {
         method: "post",
-        path: "/v1/access/signing-keys/{kid}/revoke",
+        path: `${base}/{kid}/revoke`,
         tags: ["Access"],
         summary: "Revoke a signing key",
         request: { params: z.object({ kid: z.string() }), body: body(RevokeSigningKeyRequest) },
@@ -132,133 +94,12 @@ export function accessRoutes(api) {
             409: { description: "Rotate before revoking the current key" },
         },
     }, async (c) => {
-        requireApplication(c.get("scope"));
         const ctx = c.env.tenant;
         RevokeSigningKeyRequestSchema.parse(await readJson(c.req.raw));
         const row = await ctx.store.tx((t) => ctx.signingKeys.revoke(t, c.req.param("kid")));
         ctx.config.logger.info("signing key revoked", { kid: row.id });
         return jsonResponse(200, signingKeyView(row));
     });
-    tenantRoute(api, APPLICATION, {
-        method: "get",
-        path: "/v1/access/publishable-keys",
-        tags: ["Access"],
-        summary: "List publishable keys",
-        responses: { 200: json(ListPublishableKeysResponse, "The keys, revoked ones included") },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        return jsonResponse(200, {
-            keys: (await c.env.tenant.store.tx((t) => t.publishableKeys())).map(publishableKeyView),
-        });
-    });
-    tenantRoute(api, APPLICATION, {
-        method: "post",
-        path: "/v1/access/publishable-keys",
-        tags: ["Access"],
-        summary: "Create a publishable key",
-        description: "A key a browser page on one of the origins sends as `Nylorun-Key`. Public by design; it grants the policy's anonymous scopes.",
-        request: { body: body(CreatePublishableKeyRequest) },
-        responses: {
-            200: json(PublishableKey, "The key"),
-            409: { description: "A key with this name exists" },
-        },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        const ctx = c.env.tenant;
-        const request = CreatePublishableKeyRequestSchema.parse(await readJson(c.req.raw));
-        const row = {
-            id: newPublishableKeyId(),
-            key: newPublishableKey(ctx.config.tenantId),
-            name: request.name,
-            originsJson: JSON.stringify(request.origins),
-            createdAt: new Date().toISOString(),
-            revokedAt: null,
-        };
-        await ctx.store.tx(async (t) => {
-            if ((await t.publishableKeys()).some((other) => other.name === request.name))
-                fail(409, `A publishable key named ${request.name} exists`);
-            await t.insertPublishableKey(row);
-        });
-        ctx.config.logger.info("publishable key created", { keyId: row.id });
-        return jsonResponse(200, publishableKeyView(row));
-    });
-    for (const method of ["put", "delete"])
-        tenantRoute(api, APPLICATION, {
-            method,
-            path: "/v1/access/publishable-keys/{keyId}",
-            tags: ["Access"],
-            summary: method === "put" ? "Set a publishable key's origins" : "Revoke a publishable key",
-            request: {
-                params: keyId,
-                ...(method === "put" ? { body: body(UpdatePublishableKeyRequest) } : {}),
-            },
-            responses: {
-                200: json(PublishableKey, method === "put" ? "The key" : "The key, revoked (again: unchanged)"),
-            },
-        }, async (c) => {
-            requireApplication(c.get("scope"));
-            const ctx = c.env.tenant;
-            const id = c.req.param("keyId");
-            const patch = method === "put"
-                ? {
-                    originsJson: JSON.stringify(UpdatePublishableKeyRequestSchema.parse(await readJson(c.req.raw)).origins),
-                }
-                : { revokedAt: new Date().toISOString() };
-            const row = await ctx.store.tx(async (t) => {
-                const existing = (await t.publishableKey(id)) ?? fail(404, "Publishable key not found");
-                // Revoking twice keeps the first time.
-                if (method === "delete" && existing.revokedAt !== null)
-                    return existing;
-                await t.updatePublishableKey(id, patch);
-                return { ...existing, ...patch };
-            });
-            ctx.config.logger.info(method === "put" ? "publishable key updated" : "publishable key revoked", { keyId: row.id });
-            return jsonResponse(200, publishableKeyView(row));
-        });
-    tenantRoute(api, APPLICATION, {
-        method: "post",
-        path: "/v1/access/revocations",
-        tags: ["Access"],
-        summary: "Revoke a subject",
-        description: "Ends every token minted for the subject so far, and their open streams on every process. Turns in progress continue.",
-        request: { body: body(RevokeSubjectRequest) },
-        responses: { 200: json(RevokeSubjectResponse, "The subject's new epoch") },
-    }, async (c) => {
-        requireApplication(c.get("scope"));
-        const request = RevokeSubjectRequestSchema.parse(await readJson(c.req.raw));
-        return jsonResponse(200, await revokeSubject(c.env.tenant, request.subject));
-    });
-}
-/** A publishable key as the API shows it. */
-export function publishableKeyView(row) {
-    return {
-        id: row.id,
-        name: row.name,
-        key: row.key,
-        origins: JSON.parse(row.originsJson),
-        createdAt: row.createdAt,
-        revokedAt: row.revokedAt,
-    };
-}
-/**
- * Ends every token of `subject` minted so far: bumps its epoch, then ends its open streams
- * here and, through `tenant/control`, on every other process. Running turns continue.
- */
-export async function revokeSubject(ctx, subject) {
-    const epoch = await ctx.store.tx(async (t) => {
-        const next = await t.bumpSubjectEpoch(subject, new Date().toISOString());
-        t.afterCommit(async () => {
-            endSubjectStreams(ctx.sessionStreams, subject, next);
-            const streams = ctx.sessionStreams.wiring?.streams;
-            if (streams)
-                await signalSubjectRevoked(streams, currentBasin(ctx), subject, next).catch((error) => ctx.config.logger.warn("subject revocation signal failed", {
-                    message: error instanceof Error ? error.message : String(error),
-                }));
-        });
-        return next;
-    });
-    ctx.config.logger.info("subject revoked", { epoch });
-    return { subject, epoch };
 }
 /** True when the Tenant has a current and a standby signing key. */
 function complete(rows) {

package/dist/api/http/routes/artifacts.js

@@ -32,22 +32,18 @@ import { jsonResponse } from "../respond.js";
 const OWN = {
     credentials: ["application", "subject", "token"],
     scopes: ["sessions:own"],
-    browser: true,
 };
 /** An upload: the same callers, with the file's bytes as the body. */
 const UPLOAD = { ...OWN, bytes: true };
 /** A capability link: no credential, no protocol header; the token in the path is the grant. */
 const LINK = {
-    credentials: ["application", "subject", "token", "publishable"],
+    credentials: ["application", "subject", "token"],
     scopes: "any",
-    browser: true,
     anonymous: true,
     unversioned: true,
 };
-const SETTINGS = {
-    credentials: ["application", "subject"],
-    scopes: ["tenant:settings"],
-};
+/** The Tenant's artifact limits: a Management API route (`/v1/tenant/artifacts`). */
+const SETTINGS = { credentials: ["management"], scopes: "never" };
 const json = (schema, description) => ({
     description,
     content: { "application/json": { schema } },

package/dist/api/http/routes/files.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Definition files (track R2 M4): `PUT /v1/files/sha256:{hex}` uploads one file a definition
+ * names by its content hash (a skill's), `HEAD` says whether the Tenant holds it. Application
+ * key only: definitions are the application's, not a person's.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function fileRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/http/routes/files.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { DEFINITION_FILE_MAX_BYTES } from "@nylorun/core/contracts";
+import { DefinitionFileView } from "../../components.js";
+import { normalizeContentType } from "../../../artifacts/media-types.js";
+import { hasDefinitionFile, putDefinitionFile } from "../../../tenant/definition-files.js";
+import { fail } from "../../../tenant/http.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const APPLICATION = { credentials: ["application"], scopes: "never" };
+const UPLOAD = { ...APPLICATION, bytes: true };
+const file = z.object({
+    file: z.string().meta({ description: "`sha256:` and the SHA-256 of the file's bytes, 64 lowercase hex digits" }),
+});
+const view = (description) => ({
+    description,
+    content: { "application/json": { schema: DefinitionFileView } },
+});
+/** The declared `Content-Length`, when there is one. */
+function declaredLength(request) {
+    const raw = request.headers.get("content-length");
+    return raw !== null && /^\d+$/.test(raw) ? Number(raw) : undefined;
+}
+/** The declared media type, unless it is absent or `application/octet-stream`. */
+function declaredType(request) {
+    const raw = request.headers.get("content-type") ?? undefined;
+    if (raw === undefined)
+        return undefined;
+    const type = normalizeContentType(raw);
+    if (type === undefined)
+        return fail(400, "Content-Type is not a media type");
+    return type.toLowerCase().startsWith("application/octet-stream") ? undefined : type;
+}
+export function fileRoutes(api) {
+    tenantRoute(api, UPLOAD, {
+        method: "put",
+        path: "/v1/files/{file}",
+        tags: ["Definition files"],
+        summary: "Upload a definition file",
+        description: `Stores the body, at most ${DEFINITION_FILE_MAX_BYTES} bytes, at the SHA-256 the path names; a body with another hash stores nothing (\`400\`). A file the Tenant holds already is kept as it is (\`200\`).`,
+        request: {
+            params: file,
+            body: {
+                required: true,
+                description: "The file's bytes",
+                content: { "application/octet-stream": { schema: z.string().meta({ format: "binary" }) } },
+            },
+        },
+        responses: {
+            200: view("The Tenant held the file already"),
+            201: view("The file, stored"),
+            413: { description: `Larger than ${DEFINITION_FILE_MAX_BYTES} bytes (\`limit_exceeded\`)` },
+        },
+    }, async (c) => {
+        const request = c.req.raw;
+        const length = declaredLength(request);
+        const type = declaredType(request);
+        const stored = await putDefinitionFile(c.env.tenant, c.req.param("file"), {
+            body: request.body,
+            ...(length === undefined ? {} : { declaredBytes: length }),
+            ...(type === undefined ? {} : { contentType: type }),
+        }, request.signal);
+        return jsonResponse(stored.status, stored.view);
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "head",
+        path: "/v1/files/{file}",
+        tags: ["Definition files"],
+        summary: "Whether the Runtime holds a definition file",
+        description: "`200` when the Tenant holds the file, `404` when it does not: upload it.",
+        request: { params: file },
+        responses: { 200: { description: "The Tenant holds the file" } },
+    }, async (c) => {
+        if (!(await hasDefinitionFile(c.env.tenant, c.req.param("file"))))
+            return fail(404, "The Runtime does not hold this file");
+        return new Response(null, { status: 200 });
+    });
+}

package/dist/api/http/routes/keys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Application keys (`/v1/tenant/keys`, the Management API, protocol 8): a management key
+ * creates, rotates, lists and deletes the Tenant's application keys by name. It never touches a
+ * management key, `studio` or `bootstrap`: those come only from the Tenant's machine
+ * (`nylorun-operate`, `NYLORUN_MANAGEMENT_KEY_FILE`), so a leaked management key cannot mint
+ * another. A rotated or deleted key stops authenticating on its next request.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function keyRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/http/routes/keys.js

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { DeleteOperatorKeyResponse, ListOperatorKeysResponse, PutOperatorKeyResponse, } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { operatorKeys } from "../../../tenant/operator-keys.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
+const keyId = z.object({
+    keyId: z
+        .string()
+        .meta({ description: "The key's name: `^[a-z][a-z0-9-]{0,31}$`, never `studio` or `bootstrap`" }),
+});
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+function refused(refusal) {
+    return fail(400, refusal.message, {
+        code: refusal.reason === "invalid" ? "invalid_request" : "request_rejected",
+    });
+}
+export function keyRoutes(api) {
+    tenantRoute(api, MANAGEMENT, {
+        method: "get",
+        path: "/v1/tenant/keys",
+        tags: ["Application keys"],
+        summary: "List the Tenant's keys",
+        description: "Every key of the Tenant by name, with its role (`application`, `management` or `studio`) and when it was issued. Keys themselves are never shown again.",
+        responses: { 200: json(ListOperatorKeysResponse, "The keys, by id") },
+    }, async (c) => jsonResponse(200, { keys: await operatorKeys(c.env.tenant.store).list() }));
+    tenantRoute(api, MANAGEMENT, {
+        method: "put",
+        path: "/v1/tenant/keys/{keyId}",
+        tags: ["Application keys"],
+        summary: "Create or rotate an application key",
+        description: "Issues a new application key named `keyId` and returns it this once. An application key of that name is replaced: the old one stops authenticating at once. A management key, `studio` and `bootstrap` are refused.",
+        request: { params: keyId },
+        responses: {
+            200: json(PutOperatorKeyResponse, "The new key, shown once"),
+            400: { description: "Not a key name, a reserved name, or a management key's name" },
+        },
+    }, async (c) => {
+        const put = await operatorKeys(c.env.tenant.store).put(c.req.param("keyId"), "application");
+        return "reason" in put ? refused(put) : jsonResponse(200, put);
+    });
+    tenantRoute(api, MANAGEMENT, {
+        method: "delete",
+        path: "/v1/tenant/keys/{keyId}",
+        tags: ["Application keys"],
+        summary: "Delete an application key",
+        description: "The key stops authenticating at once. A management key, `studio` and `bootstrap` are refused.",
+        request: { params: keyId },
+        responses: {
+            200: json(DeleteOperatorKeyResponse, "The key is deleted"),
+            400: { description: "Not a key name, a reserved name, or a management key's name" },
+        },
+    }, async (c) => {
+        const id = c.req.param("keyId");
+        const deleted = await operatorKeys(c.env.tenant.store).delete(id, "application");
+        if (typeof deleted !== "boolean")
+            return refused(deleted);
+        return deleted ? jsonResponse(200, { id, deleted: true }) : fail(404, `No key ${id}`);
+    });
+}

package/dist/api/http/routes/me.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `GET /v1/me` (Host feature `trusted-issuers`): who the Runtime takes the caller to be, for any
+ * credential that acts on the Tenant. It shows what a trusted issuer's token renders to (its
+ * subject, scopes, agents and sandbox grants), so an operator can check an identity file, and
+ * Studio can check a forwarded token for the `studio` scope.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import { type MeResponse as MeBody } from "@nylorun/core/contracts";
+import type { AuthScope } from "../../../tenant/context.js";
+import type { TenantEnv } from "../app.js";
+/** The caller as `GET /v1/me` reports it. */
+export declare function describeCaller(scope: AuthScope): MeBody;
+export declare function meRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/http/routes/me.js

@@ -0,0 +1,48 @@
+import { CALLER_SCOPES, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
+import { MeResponse } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+function ordered(scopes) {
+    const held = new Set(scopes);
+    return CALLER_SCOPES.filter((scope) => held.has(scope));
+}
+/** The caller as `GET /v1/me` reports it. */
+export function describeCaller(scope) {
+    switch (scope.kind) {
+        case "application":
+            return { scopes: [...SUBJECT_SCOPES], agents: "*", via: `application:${scope.principalId}` };
+        case "subject":
+            return { subject: scope.subject, scopes: ordered(scope.scopes), agents: "*", via: "subject" };
+        case "token":
+            return {
+                subject: scope.subject,
+                scopes: ordered(scope.scopes),
+                agents: scope.agents === "*" ? "*" : [...scope.agents].sort(),
+                sandboxes: [...(scope.sandboxes ?? [])],
+                via: `issuer:${scope.issuer}`,
+            };
+        case "management":
+            return { scopes: [], agents: [], via: `management:${scope.principalId}` };
+        default:
+            return fail(403, "This credential acts on no Tenant resource");
+    }
+}
+export function meRoutes(api) {
+    tenantRoute(api, { credentials: ["application", "subject", "management", "token"], scopes: "any" }, {
+        method: "get",
+        path: "/v1/me",
+        tags: ["Access"],
+        summary: "Get who the caller is",
+        description: "The subject, scopes, agents and sandbox grants of the credential that sends it: an " +
+            "application key (alone or acting for a subject), a management key " +
+            "(`via: management:<principalId>`, no scopes, no agents), or a trusted issuer's token " +
+            "(`via: issuer:<name>`).",
+        responses: {
+            200: {
+                description: "The caller",
+                content: { "application/json": { schema: MeResponse } },
+            },
+        },
+    }, (c) => jsonResponse(200, describeCaller(c.get("scope"))));
+}

package/dist/api/http/routes/reads.d.ts

@@ -0,0 +1,66 @@
+/** Read-only sub-resources and opt-in pages. The execution routes retain their contracts. */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import { z } from "zod";
+import type { TenantEnv } from "../app.js";
+export declare const pageQuery: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const sessionPageQuery: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        idle: "idle";
+        paused: "paused";
+        runnable: "runnable";
+        running: "running";
+        uncertain: "uncertain";
+        waiting: "waiting";
+    }>>;
+    sandboxId: z.ZodOptional<z.ZodString>;
+    ownerUserId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare function parseQuery<T>(schema: z.ZodType<T>, query: unknown): T;
+export declare function sessionPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>): Promise<{
+    sessions: {
+        id: string;
+        agentId: string;
+        ownerUserId: string;
+        status: "cancelled" | "completed" | "failed" | "idle" | "paused" | "runnable" | "running" | "uncertain" | "waiting";
+        activeTurnId: string | null;
+        lastTurnId: string | null;
+        sandboxId: string | null;
+        createdAt: string | null;
+        lastEventAt: string | null;
+    }[];
+    nextCursor: string | null;
+}>;
+export declare function sandboxPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>, labels: Record<string, string>): Promise<{
+    sandboxes: {
+        id: string;
+        kind: "pod" | "virtual";
+        labels: Record<string, string>;
+        spec: Record<string, unknown>;
+        state: "creating" | "ready" | "running" | "stopped";
+        pod?: {
+            desired: "deleted" | "running" | "suspended";
+            observed: "creating" | "deleting" | "expired" | "failed" | "lost" | "running" | "suspended";
+            volumeGeneration: number;
+            hostEpoch: number;
+            expiresAt?: string | undefined;
+            reason?: string | undefined;
+        } | undefined;
+        sessions: {
+            id: string;
+            activeTurnId: string | null;
+        }[];
+        createdAt: string;
+        updatedAt: string;
+    }[];
+    nextCursor: string | null;
+}>;
+export declare function readRoutes(api: OpenAPIHono<TenantEnv>): void;