@serve.zone/interfaces 32.60.0 → 32.61.0

package/ts/data/delegatedadmintoken.ts

@@ -0,0 +1,282 @@
+import { readDataElements, readDataProperty, readExactDataRecord } from '../private/dataproperties.js';
+import {
+  isReservedSecretKey, platformReservedSecretKeyPrefixes, runtimeInjectionSecretKeyPrefixes,
+  runtimeInjectionSecretKeys,
+} from './secret.js';
+
+/**
+ * A delegated administrator token (a "temp token") hands an agent a narrow, short-lived slice of
+ * one human administrator's authority, without the administrator's password or session.
+ *
+ * - Only a human administrator who signed in within five minutes mints one
+ *   (`mintDelegatedAdminToken`), for scopes named explicitly from `delegatedAdminTokenScopes`.
+ *   The plaintext token is answered exactly once; Cloudly stores only its hash.
+ * - It is exchanged with `getIdentityByToken` for a session that only the requests of its scopes
+ *   (`delegatedAdminTokenScopeRequests`) admit. Every such request re-reads the token, so the
+ *   session carries no validity of its own, and acts as `<administrator> via temp token <id>`.
+ * - It ends at its expiry, at most `maximumLifetimeMs` after the mint and never extended; when any
+ *   administrator revokes it; or when the minting administrator's credential generation changes.
+ * - A delegated session never mints, lists or revokes tokens, and no scope reaches users, roles,
+ *   human credentials, deployment tokens, authority records or organization membership.
+ */
+export const delegatedAdminTokenContract = Object.freeze({
+  /** The lifetime a mint that names none receives. */
+  defaultLifetimeMs: 60 * 60 * 1000,
+  /** The hard cap: a token lives at most one hour from its mint and is never extended. */
+  maximumLifetimeMs: 60 * 60 * 1000,
+  minimumLifetimeMs: 60 * 1000,
+  /** Every token is `delegatedAdminToken_<tokenId>_<secret>`, both parts 64 lowercase hex. */
+  tokenPrefix: 'delegatedAdminToken_',
+  /** Tokens one listing reports at most, newest first; a listing that leaves any out says so. */
+  maximumListedTokens: 256,
+  /** Secret key prefixes one token is granted at most. */
+  maximumSecretKeyPrefixes: 16,
+});
+
+/**
+ * What a token may be minted for. Each scope admits exactly the requests
+ * `delegatedAdminTokenScopeRequests` names for it, and nothing else does.
+ *
+ * - `secrets`: the operator-managed secrets of services and SecretSets: list and read their
+ *   metadata and read the ingress recipient a value is sealed to; create, rotate, retire and revoke
+ *   those whose key starts with a prefix the token was granted (`secretKeyPrefixes`, see
+ *   `isDelegatedSecretKey`; `changeSecretLifecycle` only with the actions
+ *   `delegatedAdminTokenSecretLifecycleActions` names, never `delete`). A token creates a secret
+ *   only as a launcher-environment variable, never as a file. A token minted without prefixes
+ *   creates, rotates, retires and revokes nothing.
+ * - `serviceCredentials`: a service's platform credential (`SERVEZONE_PLATFORM_AUTHORIZATION`):
+ *   inspect, ensure, rotate and revoke it.
+ */
+export const delegatedAdminTokenScopes = ['secrets', 'serviceCredentials'] as const;
+
+export type TDelegatedAdminTokenScope = typeof delegatedAdminTokenScopes[number];
+
+/** The exact requests each scope admits a delegated session on, by their wire method names. */
+export const delegatedAdminTokenScopeRequests = Object.freeze({
+  secrets: Object.freeze([
+    'getSecretIngressRecipient', 'listSecrets', 'getSecretMetadata', 'createSecret', 'rotateSecret',
+    'changeSecretLifecycle',
+  ] as const),
+  serviceCredentials: Object.freeze(['getServiceMachineCredential', 'mutateServiceMachineCredential'] as const),
+}) satisfies Readonly<Record<TDelegatedAdminTokenScope, readonly string[]>>;
+
+/** A request one scope admits, by its wire method name. */
+export type TDelegatedAdminTokenScopeRequest<TScope extends TDelegatedAdminTokenScope = TDelegatedAdminTokenScope> =
+  (typeof delegatedAdminTokenScopeRequests)[TScope][number];
+
+/** Whether `scopeArg` admits the request a wire method names. */
+export const isDelegatedAdminTokenScopeRequest = <TScope extends TDelegatedAdminTokenScope>(
+  scopeArg: TScope,
+  methodArg: unknown,
+): methodArg is TDelegatedAdminTokenScopeRequest<TScope> => (
+  (delegatedAdminTokenScopeRequests[scopeArg] as readonly unknown[]).includes(methodArg)
+);
+
+/**
+ * The `changeSecretLifecycle` actions the `secrets` scope delegates, each only for a secret whose key
+ * the token's grant covers (`isDelegatedSecretKey`). Deleting a secret stays with a human
+ * administrator: a delegated session asking for it is refused like a request outside its scope.
+ */
+export const delegatedAdminTokenSecretLifecycleActions = Object.freeze(['retire', 'revoke'] as const);
+
+/** One token, value-free. Neither the token nor its hash is ever part of it. */
+export interface IDelegatedAdminTokenMetadata {
+  /** 64 lowercase hex; the part of the token that names it. */
+  tokenId: string;
+  /** The human administrator who minted the token and whom every use acts for. */
+  userId: string;
+  /** Distinct, in `delegatedAdminTokenScopes` order. */
+  scopes: TDelegatedAdminTokenScope[];
+  /**
+   * The secret key prefixes the token creates, rotates, retires and revokes secrets under, sorted
+   * and distinct; empty when it was granted none. Only a token with the `secrets` scope carries any.
+   */
+  secretKeyPrefixes: string[];
+  createdAt: number;
+  expiresAt: number;
+  /** When an administrator revoked the token; `null` while it was never revoked. */
+  revokedAt: number | null;
+  /** The administrator who revoked it; `null` exactly when `revokedAt` is. */
+  revokedBy: string | null;
+}
+
+/** What a mint states besides the administrator's identity. */
+export interface IDelegatedAdminTokenMint {
+  scopes: TDelegatedAdminTokenScope[];
+  /** Absent: `defaultLifetimeMs`. Otherwise within `minimumLifetimeMs` and `maximumLifetimeMs`. */
+  lifetimeMs?: number;
+  /**
+   * The secret key prefixes the token may create, rotate, retire and revoke secrets under, each
+   * `isDelegatableSecretKeyPrefix`, distinct, at most `maximumSecretKeyPrefixes`; only with the
+   * `secrets` scope. Prefixes must be application-specific (`GITSYNC_`): a prefix that overlaps a
+   * reserved name is refused. Absent or empty: the token creates, rotates, retires and revokes
+   * nothing.
+   */
+  secretKeyPrefixes?: string[];
+}
+
+export interface IDelegatedAdminTokenMintResult {
+  /** The plaintext token, answered on this answer only; Cloudly keeps only its hash. */
+  token: string;
+  metadata: IDelegatedAdminTokenMetadata;
+}
+
+/**
+ * Every refusal the token requests name, as `IDelegatedAdminTokenErrorData`.
+ *
+ * - `ADMIN_AUTHORIZATION_REQUIRED`: a mint by anyone but a human administrator who signed in
+ *   within five minutes, or a listing or revocation by anyone but an administrator. A delegated
+ *   session is refused here on every request.
+ * - `DELEGATED_ADMIN_TOKEN_REQUEST_INVALID`: the request does not satisfy this contract.
+ * - `DELEGATED_ADMIN_TOKEN_NOT_FOUND`: no token has that id.
+ * - `DELEGATED_ADMIN_TOKEN_INACTIVE`: the token already ended: it expired, was revoked, or its
+ *   administrator is no longer a human administrator at the credential generation it was minted
+ *   under.
+ */
+export const delegatedAdminTokenRefusals = [
+  'ADMIN_AUTHORIZATION_REQUIRED',
+  'DELEGATED_ADMIN_TOKEN_REQUEST_INVALID',
+  'DELEGATED_ADMIN_TOKEN_NOT_FOUND',
+  'DELEGATED_ADMIN_TOKEN_INACTIVE',
+] as const;
+
+export type TDelegatedAdminTokenRefusal = typeof delegatedAdminTokenRefusals[number];
+
+export interface IDelegatedAdminTokenErrorData {
+  code: TDelegatedAdminTokenRefusal;
+  retryable: false;
+}
+
+const fail = (): never => { throw new Error('Delegated admin token contract rejected.'); };
+function requireValue(value: unknown): asserts value { if (!value) fail(); }
+const safe = <T>(operation: () => T): T => { try { return operation(); } catch { return fail(); } };
+/** Exactly this shape's keys, read once as data; an accessor is refused, never invoked. */
+const object = (value: unknown, keys: readonly string[]): Record<string, unknown> => {
+  const copy = readExactDataRecord(value, keys);
+  requireValue(copy !== null);
+  return copy;
+};
+const identifier = (value: unknown): string => {
+  requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+  return value;
+};
+const timestamp = (value: unknown): number => {
+  requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0);
+  return value;
+};
+const tokenIdPattern = /^[a-f0-9]{64}$/;
+const tokenPattern = /^delegatedAdminToken_[a-f0-9]{64}_[a-f0-9]{64}$/;
+
+/** Whether a value is a delegated admin token in its exact form; it proves nothing else. */
+export const isDelegatedAdminToken = (value: unknown): value is string => (
+  typeof value === 'string' && tokenPattern.test(value)
+);
+
+/** Whether a value names a token: 64 lowercase hex. */
+export const isDelegatedAdminTokenId = (value: unknown): value is string => (
+  typeof value === 'string' && tokenIdPattern.test(value)
+);
+
+const secretKeyPrefixPattern = /^[A-Z][A-Z0-9]*_$/;
+
+/**
+ * Whether a prefix may be granted: `^[A-Z][A-Z0-9]*_$`, and overlapping no reserved name in
+ * either direction: it neither starts with nor is the start of an entry of
+ * `platformReservedSecretKeyPrefixes` or `runtimeInjectionSecretKeyPrefixes`, and no entry of
+ * `runtimeInjectionSecretKeys` starts with it. So a granted prefix is application-specific:
+ * `GIT_`, `NODE_`, `NPM_` and `AWS_` (`AWS_CA_BUNDLE`) are refused; `GITSYNC_` is not.
+ */
+export const isDelegatableSecretKeyPrefix = (value: unknown): value is string => (
+  typeof value === 'string' && value.length <= 64 && secretKeyPrefixPattern.test(value)
+  && [...platformReservedSecretKeyPrefixes, ...runtimeInjectionSecretKeyPrefixes]
+    .every((reservedArg) => !value.startsWith(reservedArg) && !reservedArg.startsWith(value))
+  && runtimeInjectionSecretKeys.every((reservedArg) => !reservedArg.startsWith(value))
+);
+
+/**
+ * Whether a token granted `prefixesArg` creates, rotates, retires or revokes a secret of key
+ * `keyArg`, or delivers a launcher variable of that name: the key starts with a granted prefix and
+ * is not reserved (`isReservedSecretKey`).
+ */
+export const isDelegatedSecretKey = (prefixesArg: readonly string[], keyArg: string): boolean => (
+  prefixesArg.some((prefixArg) => keyArg.startsWith(prefixArg)) && !isReservedSecretKey(keyArg)
+);
+
+/** Whether a lifetime is one a mint may state. */
+export const isDelegatedAdminTokenLifetime = (value: unknown): value is number => (
+  typeof value === 'number' && Number.isSafeInteger(value)
+  && value >= delegatedAdminTokenContract.minimumLifetimeMs
+  && value <= delegatedAdminTokenContract.maximumLifetimeMs
+);
+
+/** Distinct known scopes, at least one, answered in `delegatedAdminTokenScopes` order. */
+const scopes = (value: unknown, canonical: boolean): TDelegatedAdminTokenScope[] => {
+  const entries = readDataElements(value, delegatedAdminTokenScopes.length);
+  requireValue(entries !== null && entries.length > 0 && new Set(entries).size === entries.length
+    && entries.every((entry) => delegatedAdminTokenScopes.some((scope) => scope === entry)));
+  const ordered = delegatedAdminTokenScopes.filter((scope) => entries.includes(scope));
+  requireValue(!canonical || ordered.every((scope, index) => entries[index] === scope));
+  return ordered;
+};
+
+/** Distinct grantable prefixes, at most the cap, answered sorted; `canonical` requires them sorted. */
+const secretKeyPrefixes = (value: unknown, canonical: boolean): string[] => {
+  const entries = readDataElements(value, delegatedAdminTokenContract.maximumSecretKeyPrefixes);
+  requireValue(entries !== null && new Set(entries).size === entries.length
+    && entries.every((entry) => isDelegatableSecretKeyPrefix(entry)));
+  const prefixes = (entries as string[]).slice().sort();
+  requireValue(!canonical || prefixes.every((prefix, index) => entries[index] === prefix));
+  return prefixes;
+};
+
+/** Structural copy of a mint; the backend authorizes the administrator and enforces the cap. */
+export const snapshotDelegatedAdminTokenMint = (value: unknown): IDelegatedAdminTokenMint => safe(() => {
+  const namesLifetime = readDataProperty(value, 'lifetimeMs') !== null;
+  const namesPrefixes = readDataProperty(value, 'secretKeyPrefixes') !== null;
+  const mint = object(value, ['scopes', ...(namesLifetime ? ['lifetimeMs'] : []),
+    ...(namesPrefixes ? ['secretKeyPrefixes'] : [])]);
+  const copy: IDelegatedAdminTokenMint = { scopes: scopes(mint.scopes, false) };
+  if (namesLifetime) {
+    requireValue(isDelegatedAdminTokenLifetime(mint.lifetimeMs));
+    copy.lifetimeMs = mint.lifetimeMs;
+  }
+  if (namesPrefixes) {
+    const prefixes = secretKeyPrefixes(mint.secretKeyPrefixes, false);
+    requireValue(prefixes.length === 0 || copy.scopes.includes('secrets'));
+    copy.secretKeyPrefixes = prefixes;
+  }
+  return copy;
+});
+
+/** Structural copy of listed or answered metadata. */
+export const snapshotDelegatedAdminTokenMetadata = (value: unknown): IDelegatedAdminTokenMetadata => safe(() => {
+  const metadata = object(value, ['tokenId', 'userId', 'scopes', 'secretKeyPrefixes', 'createdAt', 'expiresAt',
+    'revokedAt', 'revokedBy']);
+  requireValue(isDelegatedAdminTokenId(metadata.tokenId));
+  const createdAt = timestamp(metadata.createdAt);
+  const expiresAt = timestamp(metadata.expiresAt);
+  requireValue(expiresAt > createdAt
+    && expiresAt - createdAt <= delegatedAdminTokenContract.maximumLifetimeMs);
+  const revoked = metadata.revokedAt !== null;
+  requireValue(revoked === (metadata.revokedBy !== null));
+  const revokedAt = revoked ? timestamp(metadata.revokedAt) : null;
+  requireValue(revokedAt === null || revokedAt >= createdAt);
+  const tokenScopes = scopes(metadata.scopes, true);
+  const prefixes = secretKeyPrefixes(metadata.secretKeyPrefixes, true);
+  requireValue(prefixes.length === 0 || tokenScopes.includes('secrets'));
+  return {
+    tokenId: metadata.tokenId, userId: identifier(metadata.userId), scopes: tokenScopes,
+    secretKeyPrefixes: prefixes, createdAt, expiresAt, revokedAt,
+    revokedBy: revoked ? identifier(metadata.revokedBy) : null,
+  };
+});
+
+/** Structural copy of a mint's answer: a token in its exact form and the metadata that names it. */
+export const snapshotDelegatedAdminTokenMintResult = (value: unknown): IDelegatedAdminTokenMintResult => safe(() => {
+  const result = object(value, ['token', 'metadata']);
+  requireValue(isDelegatedAdminToken(result.token));
+  const metadata = snapshotDelegatedAdminTokenMetadata(result.metadata);
+  requireValue(result.token.slice(delegatedAdminTokenContract.tokenPrefix.length,
+    delegatedAdminTokenContract.tokenPrefix.length + 64) === metadata.tokenId && metadata.revokedAt === null);
+  return { token: result.token, metadata };
+});

package/ts/data/gateway.ts

@@ -20,8 +20,16 @@ export type TManagedRouteKind = 'letsencrypt-http01-forward';
 /**
  * DNS handling requested alongside a gateway route synchronization.
  *
- * - 'reconcile' claims or replaces exact-host manual A, AAAA, and CNAME
- *   records, including already-correct records, with gateway-managed state.
+ * - 'reconcile' creates, updates and deletes the exact-host A or AAAA record
+ *   the route's gateway DNS ownership holds. It never adopts, replaces or
+ *   deletes a record without gateway DNS ownership. The route is satisfied by
+ *   manual records only when no record at the name is owned and every manual A
+ *   or AAAA record there matches the desired type, value and proxied flag (TTL
+ *   ignored); anything else (a differing record, any CNAME, owned and manual
+ *   records together) and an operator-protected hostname is a non-retryable
+ *   `record-conflict` with no mutation. When the route stops claiming the
+ *   hostname while another enabled route on the gateway serves it, the owned
+ *   record is released to manual ownership instead of deleted.
  * - 'observe' reports DNS state without mutating it.
  * - 'skip' bypasses DNS inspection and mutation and is the default when omitted.
  */
@@ -29,6 +37,14 @@ export type TGatewayRouteDnsMode = 'reconcile' | 'observe' | 'skip';
 
 /**
  * Detailed DNS outcome reported by a gateway route synchronization.
+ *
+ * - `manual-satisfied`: every manual A or AAAA record at the name matches the desired type,
+ *   value and proxied flag; the gateway changes and claims nothing and reports them in
+ *   `records` with `managed: false`.
+ * - `managed-released`: the route no longer claims the hostname, but another enabled route on
+ *   the gateway still serves it, so the gateway released its record to manual ownership instead
+ *   of deleting it; the released record is reported in `records` with `managed: false`.
+ * - `managed-overwrote-manual` and `managed-orphan-deleted`: deprecated; no gateway reports them.
  */
 export type TGatewayRouteDnsStatus =
   | 'not-applicable'
@@ -37,8 +53,10 @@ export type TGatewayRouteDnsStatus =
   | 'managed-updated'
   | 'managed-overwrote-manual'
   | 'managed-unchanged'
+  | 'manual-satisfied'
   | 'observed-satisfied'
   | 'managed-deleted'
+  | 'managed-released'
   | 'managed-orphan-deleted'
   | 'record-missing'
   | 'target-invalid'
@@ -77,7 +95,10 @@ export interface IGatewayRouteDnsResult {
   zoneName?: string;
   nameservers?: string[];
   records?: IGatewayRouteDnsRecord[];
-  /** Prior manual records replaced by this reconciliation, preserved as evidence. */
+  /**
+   * Prior manual records replaced by this reconciliation, preserved as evidence.
+   * @deprecated No gateway replaces manual records; it accompanied `managed-overwrote-manual`.
+   */
   overwrittenRecords?: IGatewayRouteDnsRecord[];
   /** Time at which the gateway checked the DNS state, as Unix epoch milliseconds. */
   checkedAt: number;

package/ts/data/index.ts

@@ -9,6 +9,7 @@ export * from './config.js';
 export * from './corestore.js';
 export * from './corestorecontroltoken.js';
 export * from './corestorelegacyadoption.js';
+export * from './delegatedadmintoken.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
 export * from './deployment.js';

package/ts/data/secret.ts

@@ -276,6 +276,44 @@ export type TSecretDelivery = ISecretLauncherEnvironmentDelivery | ISecretFileDe
 /** A delivery of a resolved secret manifest: every owner is stated. */
 export type TSecretResolvedDelivery = ISecretResolvedLauncherEnvironmentDelivery | ISecretFileDelivery;
 
+/**
+ * Prefixes of the names the platform injects into a workload itself (`SERVEZONE_*`): a secret of
+ * such a name would replace what the platform delivers.
+ */
+export const platformReservedSecretKeyPrefixes = Object.freeze(['SERVEZONE_'] as const);
+
+/**
+ * Prefixes of the names a loader, language runtime, package manager or library reads to change
+ * what a process loads, runs or trusts (`LD_PRELOAD`, `NODE_OPTIONS`, `PYTHONPATH`, `OPENSSL_CONF`,
+ * `DOTNET_STARTUP_HOOKS`, `NPM_CONFIG_REGISTRY`, …). Matched as plain prefixes, so `PYTHON`, `PERL`,
+ * `RUBY` and `PHP` cover every name that starts with them.
+ */
+export const runtimeInjectionSecretKeyPrefixes = Object.freeze([
+  'LD_', 'DYLD_', 'NODE_', 'DENO_', 'BUN_', 'PYTHON', 'PERL', 'RUBY', 'PHP', 'JAVA_', 'JDK_', '_JAVA_', 'DOTNET_',
+  'CORECLR_', 'LUA_', 'GEM_', 'BUNDLE_', 'NPM_CONFIG_', 'PIP_', 'GLIBC_', 'MALLOC_', 'GCONV_', 'OPENSSL_', 'SSL_',
+  'CURL_', 'REQUESTS_', 'GIT_',
+] as const);
+
+/**
+ * Exact names a shell, loader, runtime or HTTP client reads to change where a process looks,
+ * connects or what it trusts or records (`CLASSPATH`, `AWS_CA_BUNDLE`, `SSLKEYLOGFILE`).
+ */
+export const runtimeInjectionSecretKeys = Object.freeze([
+  'PATH', 'HOME', 'SHELL', 'ENV', 'BASH_ENV', 'IFS', 'TMPDIR', 'LOCPATH', 'NLSPATH', 'CLASSPATH', 'HTTP_PROXY',
+  'HTTPS_PROXY', 'ALL_PROXY', 'NO_PROXY', 'FTP_PROXY', 'AWS_CA_BUNDLE', 'SSLKEYLOGFILE',
+] as const);
+
+/**
+ * Whether a secret key, or a name a secret is delivered under, is reserved: one of
+ * `runtimeInjectionSecretKeys`, or starting with an entry of `platformReservedSecretKeyPrefixes`
+ * or `runtimeInjectionSecretKeyPrefixes`. A delegated administrator token never writes such a name.
+ */
+export const isReservedSecretKey = (keyArg: string): boolean => (
+  (runtimeInjectionSecretKeys as readonly string[]).includes(keyArg)
+  || platformReservedSecretKeyPrefixes.some((prefixArg) => keyArg.startsWith(prefixArg))
+  || runtimeInjectionSecretKeyPrefixes.some((prefixArg) => keyArg.startsWith(prefixArg))
+);
+
 export const secretValueLimits = Object.freeze({
   maximumBytes: 500 * 1024,
   minimumGeneratedBytes: 16,

package/ts/requests/admin.ts

@@ -8,6 +8,9 @@ import type {
   IDeploymentMachineUserMetadata, IDeploymentMachineUserMutationResult,
   TDeploymentMachineUserMutation,
 } from '../data/deploymentmachineuser.js';
+import type {
+  IDelegatedAdminTokenMetadata, IDelegatedAdminTokenMint, IDelegatedAdminTokenMintResult,
+} from '../data/delegatedadmintoken.js';
 
 export interface IReq_Admin_GetServiceMachineCredential extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetServiceMachineCredential
@@ -198,3 +201,51 @@ export interface IReq_Cloudly_Coreflow_ReconcileBaseServices extends plugins.typ
     routingProof?: ICoreflowRoutingProofResult;
   };
 }
+
+/**
+ * Mints one delegated admin token (`delegatedAdminTokenContract`) for what the request states
+ * (`IDelegatedAdminTokenMint`: its scopes, optional `lifetimeMs` and `secretKeyPrefixes`). Requires
+ * a human administrator who signed in within five minutes; a delegated session is refused. The
+ * plaintext token is answered on this answer only and is never retrievable again, so the request is
+ * sent once and its answer goes past every traffic hook. `lifetimeMs` absent is
+ * `defaultLifetimeMs`; Cloudly refuses any lifetime above `maximumLifetimeMs`. Refusals travel as
+ * `IDelegatedAdminTokenErrorData`.
+ */
+export interface IReq_Admin_MintDelegatedAdminToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_MintDelegatedAdminToken
+> {
+  method: 'mintDelegatedAdminToken';
+  request: { identity: IIdentityCredential } & IDelegatedAdminTokenMint;
+  response: IDelegatedAdminTokenMintResult;
+}
+
+/**
+ * Lists the active delegated admin tokens, value-free, newest first: not expired, not revoked,
+ * and their administrator still a human administrator at the credential generation each was
+ * minted under. At most `delegatedAdminTokenContract.maximumListedTokens` are answered;
+ * `truncated` is true exactly when active tokens beyond them were left out, so no token that
+ * needs revoking is hidden without notice. Requires an administrator; a delegated session is
+ * refused. Refusals travel as `IDelegatedAdminTokenErrorData`.
+ */
+export interface IReq_Admin_GetDelegatedAdminTokens extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_GetDelegatedAdminTokens
+> {
+  method: 'getDelegatedAdminTokens';
+  request: { identity: IIdentityCredential };
+  response: { tokens: IDelegatedAdminTokenMetadata[]; truncated: boolean };
+}
+
+/**
+ * Revokes one active delegated admin token; once the revocation commits, no use of the token
+ * commits after it, and every session exchanged for it is refused. A success has committed.
+ * Requires an administrator, the minting one or any other; a delegated session is refused.
+ * Refusals travel as `IDelegatedAdminTokenErrorData`: a token that already does not act (revoked,
+ * expired, or its administrator's credential or role changed) is `DELEGATED_ADMIN_TOKEN_INACTIVE`.
+ */
+export interface IReq_Admin_RevokeDelegatedAdminToken extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_RevokeDelegatedAdminToken
+> {
+  method: 'revokeDelegatedAdminToken';
+  request: { identity: IIdentityCredential; tokenId: string };
+  response: { metadata: IDelegatedAdminTokenMetadata };
+}

package/ts/requests/identity.ts

@@ -7,6 +7,10 @@ import * as userInterfaces from '../data/user.js'
 
 /**
  * get the identity that then will be used to get the config
+ *
+ * A delegated admin token (`delegatedAdminTokenContract`) is exchanged here too. Its identity is
+ * `type: 'machine'`, `role: 'api'`, `userId: 'delegated-admin-token:<tokenId>'`, expiring with the
+ * token; only the requests of the token's scopes admit it, and each re-reads the token.
  */
 export interface IRequest_Any_Cloudly_CoreflowManager_GetIdentityByToken
 extends plugins.typedrequestInterfaces.implementsTR<