@k2b/cloud 0.42.0 → 0.44.0

package/src/services/identity/invocation-token.ts

@@ -1,3 +1,5 @@
+import { createHash } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 import { createRemoteJWKSet, decodeProtectedHeader, errors, type JWTVerifyGetKey, jwtVerify, SignJWT } from "jose";
 import { z } from "zod";
 import {
@@ -9,6 +11,7 @@ import {
   IDENTITY_MAX_COMPACT_TOKEN_BYTES,
   INVOCATION_CLOCK_TOLERANCE_SECONDS,
 } from "./constants";
+import { authorityFromParentInvocation } from "./invocation-authority";
 import { type PreparedIdentitySigner, prepareIdentitySigner } from "./key-ring";
 import { identityMetrics } from "./metrics";
 import { getIdentityRuntimeConfig } from "./runtime-config";
@@ -44,7 +47,7 @@ export const normalizeInvocationRequestId = (value: unknown): string | undefined
   return parsed.success ? parsed.data : undefined;
 };
 
-const InvocationPayloadSchema = z
+const InvocationPayloadBaseSchema = z
   .object({
     iss: z.string().url(),
     aud: z.string().regex(/^app:[a-z][a-z0-9-]{0,79}$/),
@@ -59,6 +62,8 @@ const InvocationPayloadSchema = z
     /** Only for an app session of the mobile app, which never acts as an administrator. */
     session_kind: z.literal("app").optional(),
     credential_id: BoundedIdentifierSchema.optional(),
+    oauth_client_id: z.string().min(1).max(200).optional(),
+    credential_expires_at: z.iso.datetime().optional(),
     scopes: z
       .array(ScopeSchema)
       .max(100)
@@ -71,50 +76,72 @@ const InvocationPayloadSchema = z
     mandate_revision: z.number().int().positive().optional(),
     workload_type: BoundedIdentifierSchema.optional(),
     workload_id: BoundedIdentifierSchema.optional(),
+    parent_invocation_id: z.uuid().optional(),
     jti: z.string().uuid(),
     iat: z.number().int().nonnegative(),
     nbf: z.number().int().nonnegative(),
     exp: z.number().int().positive(),
   })
-  .strict()
-  .superRefine((claims, context) => {
-    if (claims.exp - claims.iat !== CLOUD_INVOCATION_TOKEN_TTL_SECONDS || claims.nbf !== claims.iat) {
-      context.addIssue({ code: "custom", message: "Invocation lifetime is invalid" });
-    }
+  .strict();
 
-    if (claims.principal_type === "user") {
-      if (claims.access_subject_type !== "user" || claims.access_subject_id !== claims.sub || claims.delegated_user_id !== undefined) {
-        context.addIssue({ code: "custom", message: "User invocation authority is inconsistent" });
-      }
-      if (claims.credential_kind === "api_key") {
-        context.addIssue({ code: "custom", message: "An API key must act through a service account" });
-      }
-    } else if (claims.delegated_user_id) {
-      if (claims.access_subject_type !== "user" || claims.access_subject_id !== claims.delegated_user_id) {
-        context.addIssue({ code: "custom", message: "Delegated invocation authority is inconsistent" });
-      }
-    } else if (claims.access_subject_type !== "service_account" || claims.access_subject_id !== claims.sub) {
-      context.addIssue({ code: "custom", message: "Service-account invocation authority is inconsistent" });
-    }
-    if (claims.credential_kind === "session" && claims.principal_type !== "user") {
-      context.addIssue({ code: "custom", message: "A session invocation must use a user principal" });
-    }
-    if (claims.session_kind && claims.credential_kind !== "session") {
-      context.addIssue({ code: "custom", message: "Only a session invocation has a session kind" });
+const validateInvocationClaims = (claims: z.infer<typeof InvocationPayloadBaseSchema>, context: z.RefinementCtx, subjectProbe = false) => {
+  if (
+    (claims.parent_invocation_id
+      ? claims.exp <= claims.iat ||
+        claims.exp - claims.iat > CLOUD_INVOCATION_TOKEN_TTL_SECONDS ||
+        !claims.op.startsWith("capability.query:")
+      : claims.exp - claims.iat !== CLOUD_INVOCATION_TOKEN_TTL_SECONDS) ||
+    claims.nbf !== claims.iat
+  ) {
+    context.addIssue({ code: "custom", message: "Invocation lifetime is invalid" });
+  }
+
+  if (claims.principal_type === "user") {
+    if (claims.access_subject_type !== "user" || claims.access_subject_id !== claims.sub || claims.delegated_user_id !== undefined) {
+      context.addIssue({ code: "custom", message: "User invocation authority is inconsistent" });
     }
-    if (claims.credential_kind === "session" && claims.scopes.length > 0) {
-      context.addIssue({ code: "custom", message: "A session invocation cannot carry credential scopes" });
+    if (claims.credential_kind === "api_key") {
+      context.addIssue({ code: "custom", message: "An API key must act through a service account" });
     }
-    if (claims.credential_kind === "api_key" && !claims.credential_id) {
-      context.addIssue({ code: "custom", message: "An API-key invocation requires credential provenance" });
+  } else if (claims.delegated_user_id) {
+    if (claims.access_subject_type !== "user" || claims.access_subject_id !== claims.delegated_user_id) {
+      context.addIssue({ code: "custom", message: "Delegated invocation authority is inconsistent" });
     }
+  } else if (claims.access_subject_type !== "service_account" || claims.access_subject_id !== claims.sub) {
+    context.addIssue({ code: "custom", message: "Service-account invocation authority is inconsistent" });
+  }
+  if (claims.credential_kind === "session" && claims.principal_type !== "user") {
+    context.addIssue({ code: "custom", message: "A session invocation must use a user principal" });
+  }
+  if (claims.session_kind && claims.credential_kind !== "session") {
+    context.addIssue({ code: "custom", message: "Only a session invocation has a session kind" });
+  }
+  if (claims.credential_kind === "session" && claims.scopes.length > 0) {
+    context.addIssue({ code: "custom", message: "A session invocation cannot carry credential scopes" });
+  }
+  if (claims.credential_kind === "api_key" && !claims.credential_id) {
+    context.addIssue({ code: "custom", message: "An API-key invocation requires credential provenance" });
+  }
 
-    const mandateFields = [claims.mandate_id, claims.mandate_revision, claims.workload_type, claims.workload_id];
-    const mandateFieldCount = mandateFields.filter((value) => value !== undefined).length;
-    if (claims.credential_kind === "mandate" ? mandateFieldCount !== mandateFields.length : mandateFieldCount !== 0) {
-      context.addIssue({ code: "custom", message: "Mandate provenance is incomplete or unexpected" });
-    }
-  });
+  const mandateFields = [claims.mandate_id, claims.mandate_revision, claims.workload_type, claims.workload_id];
+  const mandateFieldCount = mandateFields.filter((value) => value !== undefined).length;
+  if (
+    claims.credential_kind === "mandate"
+      ? mandateFieldCount !== mandateFields.length && !(subjectProbe && mandateFieldCount === 0)
+      : mandateFieldCount !== 0
+  ) {
+    context.addIssue({ code: "custom", message: "Mandate provenance is incomplete or unexpected" });
+  }
+};
+
+const InvocationPayloadSchema = InvocationPayloadBaseSchema.superRefine((claims, context) => validateInvocationClaims(claims, context));
+const AppAccessProbeSchema = InvocationPayloadBaseSchema.extend({
+  token_use: z.literal("app_access_probe"),
+  act: z.object({ sub: z.literal("app:core") }).strict(),
+  op: z.literal("app-access.check"),
+  schema_hash: z.null(),
+  parent_invocation_id: z.never().optional(),
+}).superRefine((claims, context) => validateInvocationClaims({ ...claims, token_use: "invocation" }, context, true));
 
 export type CloudInvocationClaims = z.infer<typeof InvocationPayloadSchema>;
 export type InvocationAuthority = Pick<
@@ -127,6 +154,8 @@ export type InvocationAuthority = Pick<
   | "credential_kind"
   | "session_kind"
   | "credential_id"
+  | "oauth_client_id"
+  | "credential_expires_at"
   | "scopes"
   | "mandate_id"
   | "mandate_revision"
@@ -181,11 +210,23 @@ export const signInvocationToken = async (params: {
   schemaHash: string | null;
   authority: InvocationAuthority;
   requestId?: string;
+  parent?: CloudInvocationClaims;
+  expiresAt?: number;
   issuedAt?: Date;
   jti?: string;
   signer?: PreparedIdentitySigner;
   issuer?: string;
 }): Promise<{ token: string; kid: string; claims: CloudInvocationClaims }> => {
+  if (
+    params.parent &&
+    (params.parent.parent_invocation_id ||
+      params.parent.aud !== `app:${params.callingAppId}` ||
+      params.parent.aud === `app:${params.targetAppId}` ||
+      !params.operation.startsWith("capability.query:") ||
+      !isDeepStrictEqual(authorityFromParentInvocation(params.parent), params.authority))
+  ) {
+    throw new Error("Child invocation cannot widen or change its parent authority");
+  }
   const issuer = params.issuer ?? (await getIdentityRuntimeConfig()).issuer;
   const signer = params.signer ?? (await prepareIdentitySigner("invocation"));
   const issuedAt = params.issuedAt ?? new Date();
@@ -204,7 +245,8 @@ export const signInvocationToken = async (params: {
     jti: params.jti ?? crypto.randomUUID(),
     iat: issuedAtSeconds,
     nbf: issuedAtSeconds,
-    exp: issuedAtSeconds + CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+    ...(params.parent ? { parent_invocation_id: params.parent.jti } : {}),
+    exp: Math.min(issuedAtSeconds + CLOUD_INVOCATION_TOKEN_TTL_SECONDS, params.parent?.exp ?? Infinity, params.expiresAt ?? Infinity),
   });
 
   try {
@@ -222,6 +264,26 @@ export const signInvocationToken = async (params: {
   }
 };
 
+async function verifyWithKeyRefresh(
+  verify: (key: JWTVerifyGetKey) => ReturnType<typeof jwtVerify>,
+  key: JWTVerifyGetKey,
+  remote: { url: URL; state: RemoteSetState } | null,
+) {
+  try {
+    return await verify(key);
+  } catch (error) {
+    if (!(error instanceof errors.JWKSNoMatchingKey) || !remote) throw error;
+    const now = Date.now();
+    if (now - remote.state.lastForcedRefreshAt < 30_000) throw error;
+    remote.state.lastForcedRefreshAt = now;
+    identityMetrics.increment("unknown_kid_refresh");
+    const refreshed = createRemoteSet(remote.url);
+    const verified = await verify(refreshed);
+    remote.state.key = refreshed;
+    return verified;
+  }
+}
+
 /** With deferSchemaBinding, the caller must compare schema_hash after resolving live authority. */
 export const verifyInvocationToken = async (
   token: string,
@@ -239,7 +301,7 @@ export const verifyInvocationToken = async (
     const jwksUrl = options.jwksUrl ?? runtime?.invocationJwksUrl;
     const state = options.key || !jwksUrl ? null : remoteSet(jwksUrl);
     if (state && jwksUrl) remote = { url: jwksUrl, state };
-    let key = options.key ?? state?.key;
+    const key = options.key ?? state?.key;
     if (!key) throw new Error("Cloud invocation verifier has no public key source");
     assertProtectedHeader(decodeProtectedHeader(token));
     const verify = (candidate: JWTVerifyGetKey) =>
@@ -251,19 +313,7 @@ export const verifyInvocationToken = async (
         clockTolerance: INVOCATION_CLOCK_TOLERANCE_SECONDS,
         currentDate: options.now,
       });
-    let verified: Awaited<ReturnType<typeof jwtVerify>>;
-    try {
-      verified = await verify(key);
-    } catch (error) {
-      if (!(error instanceof errors.JWKSNoMatchingKey) || !remote) throw error;
-      const now = Date.now();
-      if (now - remote.state.lastForcedRefreshAt < 30_000) throw error;
-      remote.state.lastForcedRefreshAt = now;
-      identityMetrics.increment("unknown_kid_refresh");
-      key = createRemoteSet(remote.url);
-      verified = await verify(key);
-      remote.state.key = key;
-    }
+    const verified = await verifyWithKeyRefresh(verify, key, remote);
     const parsed = InvocationPayloadSchema.safeParse(verified.payload);
     if (!parsed.success || parsed.data.op !== operation || (!options.deferSchemaBinding && parsed.data.schema_hash !== schemaHash)) {
       throw new Error("Cloud invocation JWT claims do not match the target operation");
@@ -280,3 +330,158 @@ export const verifyInvocationToken = async (
 export const clearInvocationVerifierCachesForTest = (): void => {
   remoteSets.clear();
 };
+
+const AppEventInvocationClaimsSchema = z
+  .object({
+    iss: z.string().url(),
+    aud: z.string(),
+    token_use: z.literal("app_event_delivery"),
+    act: z.literal("app:core"),
+    op: z.literal("app-event.deliver"),
+    subscription_id: z.string().min(1).max(400),
+    event_id: z.uuid(),
+    payload_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    iat: z.number().int(),
+    nbf: z.number().int(),
+    exp: z.number().int(),
+    jti: z.uuid(),
+  })
+  .strict();
+
+export const appEventPayloadHash = (payload: unknown): string => createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+
+/** Core-to-app invocation, bound to one subscription, event and exact request body. */
+export const signAppEventInvocation = async (input: {
+  appId: string;
+  subscriptionId: string;
+  eventId: string;
+  payload: unknown;
+  issuer?: string;
+  signer?: PreparedIdentitySigner;
+  now?: Date;
+  jti?: string;
+}) => {
+  const issuer = input.issuer ?? (await getIdentityRuntimeConfig()).issuer;
+  const signer = input.signer ?? (await prepareIdentitySigner("invocation"));
+  const now = Math.floor((input.now?.getTime() ?? Date.now()) / 1_000);
+  if (signer.signUntil.getTime() < (now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS) * 1000)
+    throw new Error("Invocation signing key expires before the delivery token");
+  const claims = AppEventInvocationClaimsSchema.parse({
+    iss: issuer,
+    aud: `app:${AppIdSchema.parse(input.appId)}`,
+    token_use: "app_event_delivery",
+    act: "app:core",
+    op: "app-event.deliver",
+    subscription_id: input.subscriptionId,
+    event_id: input.eventId,
+    payload_hash: appEventPayloadHash(input.payload),
+    iat: now,
+    nbf: now,
+    exp: now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+    jti: input.jti ?? crypto.randomUUID(),
+  });
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg: CLOUD_IDENTITY_ALGORITHM, typ: CLOUD_INVOCATION_TOKEN_TYPE, kid: signer.kid })
+    .sign(signer.key);
+};
+
+export const verifyAppEventInvocation = async (
+  token: string,
+  input: { appId: string; subscriptionId: string; eventId: string; payload: unknown },
+  options: { issuer?: string; key?: JWTVerifyGetKey; jwksUrl?: URL; now?: Date } = {},
+): Promise<boolean> => {
+  if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return false;
+  try {
+    assertProtectedHeader(decodeProtectedHeader(token));
+    const runtime = options.issuer && (options.key || options.jwksUrl) ? null : await getIdentityRuntimeConfig();
+    const issuer = options.issuer ?? runtime!.issuer;
+    const url = options.jwksUrl ?? runtime?.invocationJwksUrl;
+    const state = options.key || !url ? null : remoteSet(url);
+    const key = options.key ?? state?.key;
+    if (!key) return false;
+    const verify = (key: JWTVerifyGetKey) =>
+      jwtVerify(token, key, {
+        algorithms: [CLOUD_IDENTITY_ALGORITHM],
+        audience: `app:${AppIdSchema.parse(input.appId)}`,
+        issuer,
+        typ: CLOUD_INVOCATION_TOKEN_TYPE,
+        clockTolerance: INVOCATION_CLOCK_TOLERANCE_SECONDS,
+        currentDate: options.now,
+      });
+    const result = await verifyWithKeyRefresh(verify, key, state && url ? { url, state } : null);
+    const claims = AppEventInvocationClaimsSchema.parse(result.payload);
+    return (
+      claims.exp - claims.iat === CLOUD_INVOCATION_TOKEN_TTL_SECONDS &&
+      claims.nbf === claims.iat &&
+      claims.subscription_id === input.subscriptionId &&
+      claims.event_id === input.eventId &&
+      claims.payload_hash === appEventPayloadHash(input.payload)
+    );
+  } catch {
+    return false;
+  }
+};
+
+/** Core-only, target-bound existence proof. It cannot authorize an application operation. */
+export const signAppAccessProbe = async (input: {
+  appId: string;
+  authority: InvocationAuthority;
+  issuer?: string;
+  signer?: PreparedIdentitySigner;
+  now?: Date;
+}) => {
+  const issuer = input.issuer ?? (await getIdentityRuntimeConfig()).issuer;
+  const signer = input.signer ?? (await prepareIdentitySigner("invocation"));
+  const now = Math.floor((input.now?.getTime() ?? Date.now()) / 1_000);
+  if (signer.signUntil.getTime() < (now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS) * 1000)
+    throw new Error("Invocation signing key expires before the app-access probe");
+  const claims = AppAccessProbeSchema.parse({
+    ...input.authority,
+    iss: issuer,
+    aud: `app:${AppIdSchema.parse(input.appId)}`,
+    token_use: "app_access_probe",
+    act: { sub: "app:core" },
+    op: "app-access.check",
+    schema_hash: null,
+    ver: CLOUD_INVOCATION_PROTOCOL_VERSION,
+    iat: now,
+    nbf: now,
+    exp: now + CLOUD_INVOCATION_TOKEN_TTL_SECONDS,
+    jti: crypto.randomUUID(),
+  });
+  const token = await new SignJWT(claims)
+    .setProtectedHeader({ alg: CLOUD_IDENTITY_ALGORITHM, typ: CLOUD_INVOCATION_TOKEN_TYPE, kid: signer.kid })
+    .sign(signer.key);
+  if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) throw new Error("App-access probe exceeds 4 KiB");
+  return token;
+};
+
+export const verifyAppAccessProbe = async (
+  token: string,
+  appId: string,
+  options: { issuer?: string; key?: JWTVerifyGetKey; jwksUrl?: URL; now?: Date } = {},
+): Promise<z.infer<typeof AppAccessProbeSchema> | null> => {
+  if (new TextEncoder().encode(token).byteLength > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return null;
+  try {
+    assertProtectedHeader(decodeProtectedHeader(token));
+    const runtime = options.issuer && (options.key || options.jwksUrl) ? null : await getIdentityRuntimeConfig();
+    const issuer = options.issuer ?? runtime!.issuer;
+    const url = options.jwksUrl ?? runtime?.invocationJwksUrl;
+    const state = options.key || !url ? null : remoteSet(url);
+    const key = options.key ?? state?.key;
+    if (!key) return null;
+    const verify = (key: JWTVerifyGetKey) =>
+      jwtVerify(token, key, {
+        algorithms: [CLOUD_IDENTITY_ALGORITHM],
+        audience: `app:${AppIdSchema.parse(appId)}`,
+        issuer,
+        typ: CLOUD_INVOCATION_TOKEN_TYPE,
+        clockTolerance: INVOCATION_CLOCK_TOLERANCE_SECONDS,
+        currentDate: options.now,
+      });
+    const result = await verifyWithKeyRefresh(verify, key, state && url ? { url, state } : null);
+    return AppAccessProbeSchema.parse(result.payload);
+  } catch {
+    return null;
+  }
+};

package/src/services/identity/issue-invocation.ts

@@ -7,6 +7,7 @@ import { canUseApp } from "../app-access";
 import { recordAppAccessDenied } from "../app-access-metrics";
 import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS } from "./constants";
 import { resolveInvocationAuthority } from "./invocation-actor";
+import { matchesInvocationSubject } from "./invocation-authority";
 import { type InvocationAuthority, signInvocationToken } from "./invocation-token";
 import { readIdentityGroupsAdmin } from "./runtime-config";
 
@@ -32,6 +33,7 @@ export const resolveIssuanceAuthority = async (
 
 type RegisteredAppAccessOptions = {
   db?: SQL;
+  signal?: AbortSignal;
   getApp?: (id: string) => Promise<Pick<AppMeta, "id" | "access"> | null>;
 };
 
@@ -40,8 +42,10 @@ export const requireRegisteredAppAccess = async (
   appId: string,
   options: RegisteredAppAccessOptions = {},
 ): Promise<void> => {
+  options.signal?.throwIfAborted();
   const app = await (options.getApp ?? getApp)(appId).catch(() => null);
-  if (!app || !authority || !(await canUseApp(authority, app, { db: options.db }))) {
+  if (!app || !authority || !(await canUseApp(authority, app, { db: options.db, signal: options.signal }))) {
+    options.signal?.throwIfAborted();
     if (app) recordAppAccessDenied(app.id);
     throw new AppAccessDeniedError(app ?? { id: appId });
   }
@@ -56,12 +60,16 @@ export const issueInvocationToken = async (
     sign?: typeof signInvocationToken;
   } = {},
 ): ReturnType<typeof signInvocationToken> => {
+  dependencies.signal?.throwIfAborted();
   const authority = await (dependencies.resolve ?? resolveIssuanceAuthority)(
     params.authority,
     params.callingAppId,
     dependencies.db,
     dependencies.groupsAdmin,
   );
+  if (params.parent && (!authority || !matchesInvocationSubject(params.parent, authority)))
+    throw new AppAccessDeniedError({ id: params.targetAppId });
   await requireRegisteredAppAccess(authority, params.targetAppId, dependencies);
+  dependencies.signal?.throwIfAborted();
   return (dependencies.sign ?? signInvocationToken)(params);
 };

package/src/services/identity/models-only-auth.ts

@@ -1,10 +1,12 @@
-import { AI_INFERENCE_SCOPE, type User } from "../../contracts/shared";
+import { AI_INFERENCE_SCOPE } from "../../contracts/shared";
+import type { AccessSubject } from "../../server/services/access";
 import { isAccountExpired } from "../account-model";
 import { serviceAccountCredentials } from "../service-account-credentials";
+import { isStandaloneServiceAccountKind } from "../service-accounts";
 
 export const authenticateModelsOnlyCredential = async (
   token: string | null | undefined,
-): Promise<{ user: User; credentialId: string } | null> => {
+): Promise<{ subject: AccessSubject; credentialId: string } | null> => {
   if (!token || !serviceAccountCredentials.isApiToken(token)) return null;
   const authenticated = await serviceAccountCredentials.authenticateApiToken(token);
   if (!authenticated) return null;
@@ -14,12 +16,19 @@ export const authenticateModelsOnlyCredential = async (
     credential.status !== "active" ||
     credential.serviceAccountId !== serviceAccount.id ||
     serviceAccount.status !== "active" ||
+    credential.scopes.length !== 1 ||
+    credential.scopes[0] !== AI_INFERENCE_SCOPE
+  )
+    return null;
+  if (isStandaloneServiceAccountKind(serviceAccount.kind)) {
+    return { subject: { type: "service_account", serviceAccountId: serviceAccount.id }, credentialId: credential.id };
+  }
+  if (
     serviceAccount.kind !== "user_delegated" ||
     !delegatedUser ||
     serviceAccount.delegatedUserId !== delegatedUser.id ||
-    !credential.scopes.includes(AI_INFERENCE_SCOPE) ||
     isAccountExpired(delegatedUser.accountExpires)
   )
     return null;
-  return { user: delegatedUser, credentialId: credential.id };
+  return { subject: { type: "user", userId: delegatedUser.id }, credentialId: credential.id };
 };

package/src/services/identity/nested-invocation.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import type { RequestCredentialProof } from "../../server/middleware/auth";
+import { resolveOAuthTokenActor } from "../oauth-tokens";
+import { requestCacheRedis } from "../request-cache-redis";
+import { getOverview } from "../service-account-credentials";
+import { loadJwtSessionIdentity } from "../session/user";
+import { CLOUD_INVOCATION_TOKEN_TTL_SECONDS, IDENTITY_MAX_COMPACT_TOKEN_BYTES } from "./constants";
+import type { CloudInvocationClaims } from "./invocation-token";
+import { getIdentityRuntimeConfig } from "./runtime-config";
+
+// The first consumer performs one resource-reader check. Budget exactly that
+// dependency: one Query, one hop, no recursive fan-out or automatic retries.
+// Optional lease setup may spend at most 1% of the parent's 30-second token
+// lifetime (300 ms), taken from the original operation's remaining budget.
+export const NESTED_INVOCATION_SETUP_BUDGET_MS = (CLOUD_INVOCATION_TOKEN_TTL_SECONDS * 1000) / 100;
+
+const ProofSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("session"),
+      userId: z.uuid(),
+      sid: z.uuid(),
+      authEpoch: z.number().int().nonnegative(),
+      expiresAt: z.iso.datetime(),
+    })
+    .strict(),
+  z.object({ kind: z.literal("oauth"), payload: z.record(z.string(), z.unknown()) }).strict(),
+  z.object({ kind: z.literal("api_key"), credentialId: z.uuid() }).strict(),
+]);
+const LeaseSchema = z
+  .object({
+    appId: z.string(),
+    deadline: z.number().int().positive(),
+    origin: z.enum(["http", "app", "assistant", "mcp"]),
+    proof: ProofSchema.optional(),
+    assistantTurn: z.object({ conversationId: z.uuid(), turnId: z.uuid() }).strict().optional(),
+  })
+  .strict()
+  .refine((lease) => (lease.origin === "assistant") === !!lease.assistantTurn, { message: "Turn authority requires the Assistant origin" });
+export type NestedInvocationLease = z.infer<typeof LeaseSchema>;
+
+const key = (id: string) => `identity:nested:v1:${id}`;
+const TAKE = `local value = redis.call('GET', KEYS[1])
+if not value or redis.call('EXISTS', KEYS[2]) == 1 then return nil end
+redis.call('SET', KEYS[2], '1', 'PX', ARGV[1])
+return value`;
+
+export const nestedInvocationLeases = {
+  async create(claims: CloudInvocationClaims, lease: NestedInvocationLease, signal?: AbortSignal): Promise<void> {
+    const value = LeaseSchema.parse(lease);
+    const ttl = Math.min(claims.exp * 1000, value.deadline) - Date.now();
+    if (ttl <= 0) throw new Error("Invocation expired");
+    const json = JSON.stringify(value);
+    if (Buffer.byteLength(json) > IDENTITY_MAX_COMPACT_TOKEN_BYTES)
+      throw new Error("Invocation lease exceeds the identity metadata budget");
+    const client = await requestCacheRedis();
+    signal?.throwIfAborted();
+    await client.send("SET", [key(claims.jti), json, "PX", String(ttl), "NX"]);
+    // A command already sent cannot be cancelled. Remove its late result when
+    // the bounded setup has released the original dispatch in the meantime.
+    if (signal?.aborted) {
+      await client.send("DEL", [key(claims.jti)]);
+      signal.throwIfAborted();
+    }
+  },
+  async read(id: string): Promise<NestedInvocationLease | null> {
+    const value = await (await requestCacheRedis()).send("GET", [key(id)]);
+    if (typeof value !== "string" || Buffer.byteLength(value) > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return null;
+    const parsed = LeaseSchema.safeParse(JSON.parse(value));
+    return parsed.success && parsed.data.deadline > Date.now() ? parsed.data : null;
+  },
+  async take(id: string): Promise<NestedInvocationLease | null> {
+    const value = await (await requestCacheRedis()).send("EVAL", [
+      TAKE,
+      "2",
+      key(id),
+      `${key(id)}:used`,
+      String(CLOUD_INVOCATION_TOKEN_TTL_SECONDS * 1000),
+    ]);
+    if (typeof value !== "string" || Buffer.byteLength(value) > IDENTITY_MAX_COMPACT_TOKEN_BYTES) return null;
+    const parsed = LeaseSchema.safeParse(JSON.parse(value));
+    return parsed.success && parsed.data.deadline > Date.now() ? parsed.data : null;
+  },
+  async revoke(id: string): Promise<void> {
+    await (await requestCacheRedis()).send("DEL", [key(id)]);
+  },
+};
+
+/** Recheck the source's revocation coordinates; no reusable credential is stored. */
+export const isNestedSourceCurrent = async (
+  proof: RequestCredentialProof,
+  parent: Pick<CloudInvocationClaims, "sub" | "credential_kind" | "credential_id" | "principal_type" | "scopes">,
+): Promise<boolean> => {
+  if (proof.kind !== parent.credential_kind) return false;
+  if (proof.kind === "session") {
+    return (
+      proof.userId === parent.sub &&
+      Date.parse(proof.expiresAt) > Date.now() &&
+      !!(await loadJwtSessionIdentity({ userId: proof.userId, sid: proof.sid, authEpoch: proof.authEpoch }))
+    );
+  }
+  if (proof.kind === "api_key") {
+    if (proof.credentialId !== parent.credential_id) return false;
+    const credential = await getOverview({ id: proof.credentialId });
+    return (
+      !!credential &&
+      credential.status === "active" &&
+      credential.serviceAccountId === parent.sub &&
+      (!credential.expiresAt || Date.parse(credential.expiresAt) > Date.now()) &&
+      parent.scopes.length === credential.scopes.length &&
+      parent.scopes.every((scope) => credential.scopes.includes(scope))
+    );
+  }
+  if (typeof proof.payload.exp !== "number" || proof.payload.exp * 1000 <= Date.now()) return false;
+  const current = await resolveOAuthTokenActor(proof.payload, (await getIdentityRuntimeConfig()).groupsAdmin);
+  return (
+    !!current &&
+    current.kind === parent.principal_type &&
+    (current.kind === "user" ? current.user.id : current.serviceAccount.id) === parent.sub &&
+    parent.scopes.every((scope) => current.scopes.includes(scope))
+  );
+};
+
+export const nestedSourceDeadline = (proof: RequestCredentialProof | undefined): number => {
+  if (proof?.kind === "session") return Date.parse(proof.expiresAt);
+  if (proof?.kind === "oauth") return typeof proof.payload.exp === "number" ? proof.payload.exp * 1000 : 0;
+  return Infinity;
+};