@zgeoff/atc 2.15.1 → 2.16.0

package/src/daemon/drain-inbox.ts

@@ -0,0 +1,85 @@
+import { PROTOCOL_V } from '../protocol/protocol';
+import type { SessionID } from '../shared/session-id';
+import type { MessageOwner } from '../store/message-owner';
+import type { MessageRecord } from '../store/message-record';
+import type { TapClient } from './daemon-context';
+import type { TapGeneration, TapRegistry } from './tap-registry';
+
+/**
+ * What a drain reads from: the taps, the owner a linked tap reads messages
+ * under (the session's atc id and agent session id, or null for a session
+ * the daemon does not hold), and the store's pending messages for an owner.
+ */
+export interface InboxSource {
+  readonly taps: TapRegistry<TapClient>;
+  readonly findLinkedOwner: (sessionID: SessionID) => MessageOwner | null;
+  readonly collectPendingMessages: (owner: MessageOwner) => Promise<MessageRecord[]>;
+}
+
+/**
+ * Hands the session's tap the oldest pending message it has not taken. The
+ * backlog is read before anything is sent, so a tap's ok response is always
+ * queued ahead of its first message, and one message goes per call: the
+ * tap's ack calls it again, so the backlog never outgrows the connection's
+ * outbound queue. The drain is bound to the tap it found before the read: a
+ * tap another attach made while the read waited gets nothing from it.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- the drain claims deliveries in the tap registry it is given
+export async function drainInbox(sessionID: SessionID, source: InboxSource): Promise<void> {
+  const linkedOwner = source.findLinkedOwner(sessionID);
+  const tap = source.taps.findTap(sessionID);
+
+  if (linkedOwner === null || tap === null) {
+    return;
+  }
+
+  // A tap a principal holds takes only the messages sent to this atc id:
+  // another session that shares the agent session id may be out of its
+  // reach.
+  const owner = tap.linked ? linkedOwner : { atcID: linkedOwner.atcID };
+
+  try {
+    const pending = await source.collectPendingMessages(owner);
+
+    for (const record of pending) {
+      if (sendInboxMessage(sessionID, record, tap, source.taps)) {
+        return;
+      }
+    }
+  } catch {}
+}
+
+// Hands one pending message to the tap the drain was made for, once, and
+// reports whether it did. An unlinked tap takes only a message sent to the
+// session's own atc id. The event goes to the tap connection alone: it never
+// reaches other clients, the events socket, or hooks.
+function sendInboxMessage(
+  sessionID: SessionID,
+  record: MessageRecord,
+  tap: TapGeneration,
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a delivery claims the message in the registry
+  taps: TapRegistry<TapClient>,
+): boolean {
+  if (!tap.linked && record.atcID !== sessionID) {
+    return false;
+  }
+
+  const client = taps.claimDelivery(sessionID, record.id, tap.generation);
+
+  if (client === null) {
+    return false;
+  }
+
+  client.sendEvent({
+    v: PROTOCOL_V,
+    ev: 'InboxMessage',
+    s: sessionID,
+    message: record.id,
+    from: record.from,
+    text: record.text,
+    sentAt: record.sentAt,
+  });
+
+  return true;
+}

package/src/daemon/imp-client-port.ts

@@ -1,14 +1,17 @@
 import { createImpClient, openExecSession, openReverseForward } from '@zgeoff/imp-client';
 import type { ExecOutcome, ImpClient } from '@zgeoff/imp-client';
+import { isRecord } from '../shared/report';
 import type {
   ImpCommand,
   ImpCommandResult,
   ImpCreateSpec,
   ImpFeatures,
+  ImpIdentity,
   ImpLease,
   ImpPort,
   ImpRelayConnection,
   ImpReverseForward,
+  ImpSecret,
   ImpSessionConnection,
   ImpSessionHandlers,
   ImpSessionOutcome,
@@ -48,11 +51,79 @@ export class ImpClientPort implements ImpPort {
     this.readToken = options.readToken;
   }
 
-  // An impd from before the flags has neither.
+  // A flag counts only as a literal true: an impd from before a flag has
+  // it false, and so does one that sends anything else in its place.
   readonly readFeatures = async (): Promise<ImpFeatures> => {
     const info = await this.tryCall((client) => client.system.info());
 
-    return info.features ?? { sessionOffsets: false, leases: false };
+    const features: Readonly<Record<string, unknown>> | undefined = info.features;
+
+    return {
+      sessionOffsets: features?.['sessionOffsets'] === true,
+      leases: features?.['leases'] === true,
+      grantableTokens: features?.['grantableTokens'] === true,
+      secretRebind: features?.['secretRebind'] === true,
+    };
+  };
+
+  // An impd from before grantable lists sends none, which grants nothing.
+  readonly readIdentity = async (): Promise<ImpIdentity> => {
+    const identity = await this.tryCall((client) => client.tokens.whoami());
+
+    return {
+      kind: identity.kind,
+      name: identity.name,
+      scope: identity.scope,
+      imps: identity.imps === null ? null : [...identity.imps],
+      grantable: [...(identity.grantable ?? [])],
+    };
+  };
+
+  readonly readSecrets = async (): Promise<readonly ImpSecret[]> => {
+    const secrets = await this.tryCall((client) => client.secrets.list());
+
+    return secrets.map((secret) => ({
+      name: secret.name,
+      kind: secret.kind,
+      rules: secret.rules.map((rule) => ({
+        host: rule.host,
+        header: rule.header,
+        scheme: rule.scheme,
+        ...(rule.user === undefined ? {} : { user: rule.user }),
+      })),
+      imps: [...secret.imps],
+    }));
+  };
+
+  readonly readGrants = async (name: string): Promise<readonly string[]> => {
+    const grants = await this.tryCall((client) => client.grants.list({ name }));
+
+    return [...grants];
+  };
+
+  readonly createGrant = async (name: string, secret: string): Promise<void> => {
+    await this.tryCall((client) => client.grants.add({ name, secret }));
+  };
+
+  // A grant impd no longer holds is no grant to revoke; a missing imp or
+  // secret still rejects.
+  readonly removeGrant = async (name: string, secret: string): Promise<boolean> => {
+    try {
+      await this.tryCall((client) => client.grants.delete({ name, secret }));
+
+      return true;
+    } catch (error) {
+      if (
+        error instanceof ImpPortError &&
+        error.code === 'NOT_FOUND' &&
+        isRecord(error.data) &&
+        error.data['kind'] === 'grant'
+      ) {
+        return false;
+      }
+
+      throw error;
+    }
   };
 
   readonly readImp = async (name: string): Promise<ImpView | null> => {
@@ -60,6 +131,7 @@ export class ImpClientPort implements ImpPort {
       const imp = await this.tryCall((client) => client.imps.get({ name }));
 
       return {
+        id: imp.id,
         name: imp.name,
         state: imp.state,
         leases: (imp.leases?.leases ?? []).map((lease) => toLease(lease)),
@@ -83,7 +155,7 @@ export class ImpClientPort implements ImpPort {
       }),
     );
 
-    return { name: imp.name, state: imp.state, leases: [], otherLeaseCount: 0 };
+    return { id: imp.id, name: imp.name, state: imp.state, leases: [], otherLeaseCount: 0 };
   };
 
   readonly acquireLease = async (

package/src/daemon/imp-port.ts

@@ -9,6 +9,23 @@ export interface ImpPort {
   // impd's capability flags; an impd without them has neither.
   readonly readFeatures: () => Promise<ImpFeatures>;
 
+  // The caller's own identity: its scope, the imps it may reach, and the
+  // secrets it may grant.
+  readonly readIdentity: () => Promise<ImpIdentity>;
+
+  // Every secret impd holds, with its rules and never its value.
+  readonly readSecrets: () => Promise<readonly ImpSecret[]>;
+
+  // The names of the secrets granted to an imp.
+  readonly readGrants: (name: string) => Promise<readonly string[]>;
+
+  // Grants a secret to an imp; granting one it already holds changes
+  // nothing, and nothing in the result distinguishes the two.
+  readonly createGrant: (name: string, secret: string) => Promise<void>;
+
+  // Revokes a secret from an imp, and reports whether impd held the grant.
+  readonly removeGrant: (name: string, secret: string) => Promise<boolean>;
+
   // The imp under a name, or null when impd holds none.
   readonly readImp: (name: string) => Promise<ImpView | null>;
   readonly createImp: (spec: ImpCreateSpec) => Promise<ImpView>;
@@ -51,11 +68,54 @@ export interface ImpPort {
 export interface ImpFeatures {
   readonly sessionOffsets: boolean;
   readonly leases: boolean;
+
+  // Tokens limited to some imps may grant a list of secrets to them.
+  readonly grantableTokens: boolean;
+
+  // A rebound or recreated secret drops its grants and leaves a token's
+  // list of grantable secrets behind.
+  readonly secretRebind: boolean;
+}
+
+type ImpScope = 'read' | 'exec' | 'manage';
+
+export interface ImpIdentity {
+  readonly kind: 'token' | 'ssh' | 'tailnet' | 'dashboard';
+  readonly name: string;
+  readonly scope: ImpScope;
+
+  // Imp name patterns with `*` for any run of characters; null reaches
+  // every imp on the host.
+  readonly imps: readonly string[] | null;
+
+  // The secrets the caller may grant to the imps it reaches and revoke
+  // from them.
+  readonly grantable: readonly string[];
+}
+
+export interface ImpSecret {
+  readonly name: string;
+  readonly kind: 'anthropic' | 'custom' | 'github' | 'npm';
+  readonly rules: readonly ImpSecretRule[];
+
+  // The imps holding a grant of the secret.
+  readonly imps: readonly string[];
+}
+
+// How impd adds a secret to requests for one host.
+export interface ImpSecretRule {
+  readonly host: string;
+  readonly header: string;
+  readonly scheme: 'basic' | 'bearer' | 'raw';
+  readonly user?: string;
 }
 
 export type ImpState = 'creating' | 'running' | 'sleeping' | 'stopped' | 'error';
 
 export interface ImpView {
+  // impd's id for this imp, which a new imp made under the same name never
+  // shares.
+  readonly id: string;
   readonly name: string;
   readonly state: ImpState;
 

package/src/daemon/is-imp-name-allowed.ts

@@ -0,0 +1,38 @@
+/**
+ * Whether an imp name matches one of a token's imp patterns, as impd
+ * matches them: each pattern is an imp name with `*` for any run of
+ * characters, including none, so `dev-*` matches `dev-` and `dev-a1`, and
+ * a pattern without `*` matches only its own name.
+ */
+export function isImpNameAllowed(patterns: readonly string[], name: string): boolean {
+  return patterns.some((pattern) => isPatternMatch(pattern, name));
+}
+
+function isPatternMatch(pattern: string, name: string): boolean {
+  const [first = '', ...rest] = pattern.split('*');
+  const last = rest.pop();
+
+  if (last === undefined) {
+    return name === first;
+  }
+
+  if (name.length < first.length + last.length || !name.startsWith(first) || !name.endsWith(last)) {
+    return false;
+  }
+
+  // Each middle part in order, between the prefix and the suffix.
+  let at = first.length;
+  const end = name.length - last.length;
+
+  for (const part of rest) {
+    const found = name.indexOf(part, at);
+
+    if (found === -1 || found + part.length > end) {
+      return false;
+    }
+
+    at = found + part.length;
+  }
+
+  return true;
+}

package/src/daemon/is-own-hook-event.ts

@@ -0,0 +1,19 @@
+import type { AgentID } from '../shared/agent-id';
+
+/**
+ * Whether a hook line, judged by the agent it carries, comes from the
+ * harness atc started for its session rather than from a harness nested
+ * inside it, which inherits the session's environment and so reports under
+ * the same session. A line carrying an agent is the session's own when that
+ * agent is the session's. A line without one comes from a hook command that
+ * carries no agent flag, and stays the session's own until a line carrying
+ * the session's agent arrives from the same terminal: from then on the
+ * session's own hooks are known to carry it.
+ */
+export function isOwnHookEvent(
+  lineAgent: AgentID | undefined,
+  sessionAgent: AgentID,
+  hasAgentHookLines: boolean,
+): boolean {
+  return lineAgent === undefined ? !hasAgentHookLines : lineAgent === sessionAgent;
+}

package/src/daemon/is-tree-in-reach.ts

@@ -0,0 +1,32 @@
+import type { SessionID } from '../shared/session-id';
+import type { TargetAccess, TargetGrant } from './target-access';
+
+// A session as the tree check reads it: its id, its parent if it has one,
+// and the target it is bound to.
+interface TreeMember extends TargetGrant {
+  readonly id: SessionID;
+  readonly parent: SessionID | null;
+}
+
+/**
+ * Whether the access reaches every session in the tree the given session
+ * belongs to: its top-level session and each sub-session of that one. A
+ * session the list does not hold, or one whose parent it does not hold,
+ * is out of reach.
+ */
+export function isTreeInReach(
+  sessions: readonly TreeMember[],
+  id: SessionID,
+  access: TargetAccess,
+): boolean {
+  const session = sessions.find((x) => x.id === id);
+
+  if (session === undefined) {
+    return false;
+  }
+
+  const root = session.parent ?? session.id;
+  const tree = sessions.filter((x) => x.id === root || x.parent === root);
+
+  return tree.some((x) => x.id === root) && tree.every((x) => access.canUse(x));
+}

package/src/daemon/parse-hook-line.ts

@@ -23,8 +23,11 @@ export function parseHookLine(line: string): HookEvent | null {
     return null;
   }
 
+  const agent = parsed['agent'];
+
   return {
     atcId: toSessionID(parsed['atcId']),
+    ...(typeof agent === 'string' && agent !== '' ? { agent } : {}),
     event: parsed['event'],
     payload: parsed['payload'],
   };

package/src/daemon/session-runtime.ts

@@ -46,6 +46,11 @@ export class SessionRuntime {
   // later dropped may be restarting, so it keeps the inbox open.
   tapAttached = false;
 
+  // Whether a hook line carrying the session's agent arrived since the
+  // terminal last booted. Once one has, the session's own hooks are known
+  // to carry it, and a line without one comes from another harness.
+  hasAgentHookLines = false;
+
   // Returns the boot-scoped state to how a fresh terminal starts, at the
   // dims it boots with: no SessionStart yet and no tap since. Every path
   // that boots a new terminal for an existing session runs it, so a revived
@@ -54,6 +59,7 @@ export class SessionRuntime {
     this.dims = dims;
     this.startedAt = null;
     this.tapAttached = false;
+    this.hasAgentHookLines = false;
   }
 
   dispose(): void {

package/src/daemon/sessions.ts

@@ -479,8 +479,15 @@ export class SessionManager {
   // Adopts a headless session back into a terminal: a fresh PTY resumes the
   // same agent session id. On a remote host the host wakes first, and a
   // harness still running inside it is attached rather than started again;
-  // every other session left asleep on that host comes back with it.
-  async adoptTerminal(id: SessionID, cols: number, rows: number): Promise<Session | null> {
+  // every other session left asleep on that host comes back with it. The
+  // caller's check runs again after each await, and a failed check leaves
+  // the session as it was.
+  async adoptTerminal(
+    id: SessionID,
+    cols: number,
+    rows: number,
+    canProceed: () => boolean = () => true,
+  ): Promise<Session | null> {
     const s = this.sessions.find((x) => x.id === id);
 
     if (!s || s.pty !== null || s.agentSessionID === undefined || this.adopting.has(id)) {
@@ -489,7 +496,7 @@ export class SessionManager {
 
     const settled = await this.isRollbackSettled(id);
 
-    if (!settled) {
+    if (!settled || !canProceed()) {
       return null;
     }
 
@@ -516,9 +523,11 @@ export class SessionManager {
       this.adopting.delete(id);
     }
 
-    // A kill, a second adopt, or a failed spawn's rollback can land while
-    // the host wakes.
+    // A kill, a second adopt, a failed spawn's rollback, or a change that
+    // takes the session out of the caller's reach can land while the host
+    // wakes.
     if (
+      !canProceed() ||
       s.pty !== null ||
       !this.sessions.includes(s) ||
       this.rollingBack.has(id) ||
@@ -729,6 +738,7 @@ export class SessionManager {
     id: SessionID = mintSessionID(),
     target = 'local',
     materialized: MaterializedSpawn | null = null,
+    requireInReach: () => void = () => {},
   ): Promise<Session> {
     const adapter = this.findAdapter(agent);
 
@@ -751,6 +761,10 @@ export class SessionManager {
       ...overrides,
     });
 
+    // The caller's check runs again once the host is ready, before the
+    // harness starts.
+    requireInReach();
+
     const binding = this.mintBridgeBinding(id, target, execution.identity, hostKey);
 
     const pty = provider.spawnHarness({
@@ -1248,7 +1262,8 @@ export class SessionManager {
   // every harness on it kept inside, and fails whole when the host stays
   // awake. A dead session on a target that can destroy its host is not
   // forgotten by a kill: forgetting it destroys the host, which takes a
-  // confirmed forget.
+  // confirmed forget. The set is taken before the first await, so a
+  // sub-session spawned while the kill waits on a host is not part of it.
   async kill(id: SessionID): Promise<void> {
     const s = this.sessions.find((x) => x.id === id);
 
@@ -1256,11 +1271,15 @@ export class SessionManager {
       return;
     }
 
+    const children = this.collectChildren(id);
+
     if (s.pty) {
       await this.stopHarness(s);
 
-      for (const child of this.collectChildren(id)) {
-        await this.tryStopHarness(child);
+      for (const child of children) {
+        if (this.sessions.includes(child) && child.parent === id) {
+          await this.tryStopHarness(child);
+        }
       }
     } else {
       if (this.findProvider(s)?.capabilities.destroy === true) {
@@ -1271,8 +1290,7 @@ export class SessionManager {
         );
       }
 
-      this.updateForgottenChildren(id);
-      this.remove(s);
+      this.removeWithChildren(s, children);
     }
 
     await this.writeFleet();
@@ -1288,7 +1306,9 @@ export class SessionManager {
    * kept asleep in that host is refused until the host wakes. Its dead
    * sub-sessions on other hosts go with it, unless their own target can
    * destroy their host, and its live ones become top-level. A failed destroy
-   * throws before anything is forgotten.
+   * throws before anything is forgotten. The sub-sessions it may forget are
+   * taken before the first await; one spawned while the forget waits on a
+   * host becomes top-level.
    */
   async forget(id: SessionID): Promise<boolean> {
     const s = this.sessions.find((x) => x.id === id);
@@ -1297,6 +1317,7 @@ export class SessionManager {
       return false;
     }
 
+    const children = this.collectChildren(id);
     const provider = this.findProvider(s);
     const destroys = provider !== null && provider.capabilities.destroy && s.hostKey === s.id;
 
@@ -1330,8 +1351,7 @@ export class SessionManager {
       this.killTerminal(s);
     }
 
-    this.updateForgottenChildren(id);
-    this.remove(s);
+    this.removeWithChildren(s, children);
 
     await this.writeFleet();
 
@@ -1340,22 +1360,42 @@ export class SessionManager {
     return destroys;
   }
 
-  // A forgotten parent's dead sub-sessions go with it, except one whose own
-  // target can destroy its host: forgetting that one destroys the host, which
-  // takes its own confirmed forget. Every sub-session that stays becomes
-  // top-level.
-  private updateForgottenChildren(id: SessionID): void {
-    for (const child of this.collectChildren(id)) {
+  // Removes a forgotten session and its dead sub-sessions, except one whose
+  // own target can destroy its host: forgetting that one destroys the host,
+  // which takes its own confirmed forget. Only a sub-session among the given
+  // ones may go. Every sub-session that stays becomes top-level before the
+  // session's removal is announced, and is announced after it, so no
+  // announcement ever finds a sub-session whose parent is gone or a parent
+  // standing without the sub-sessions that leave with it.
+  private removeWithChildren(s: Session, forgettable: readonly Session[]): void {
+    const kept: Session[] = [];
+    const dropped: Session[] = [];
+
+    for (const child of this.collectChildren(s.id)) {
       const live = child.pty !== null || (child.kind === 'headless' && child.state !== 'exited');
 
-      if (live || this.findProvider(child)?.capabilities.destroy === true) {
+      if (
+        live ||
+        !forgettable.includes(child) ||
+        this.findProvider(child)?.capabilities.destroy === true
+      ) {
         child.parent = null;
 
-        this.onEvent('state', child);
+        kept.push(child);
       } else {
-        this.remove(child);
+        dropped.push(child);
       }
     }
+
+    this.remove(s);
+
+    for (const child of kept) {
+      this.onEvent('state', child);
+    }
+
+    for (const child of dropped) {
+      this.remove(child);
+    }
   }
 
   /**

package/src/daemon/tap-registry.ts

@@ -4,6 +4,23 @@ import type { SessionID } from '../shared/session-id';
 interface TapEntry<TClient> {
   readonly client: TClient;
   readonly claimed: Set<MessageID>;
+
+  // Whether the tap also takes messages held under the session's agent
+  // session id, as opposed to its atc id alone.
+  readonly linked: boolean;
+
+  // Which attach made this tap; every attach makes a new one.
+  readonly generation: number;
+}
+
+/**
+ * A session's tap as a drain finds it before it waits: the attach that made
+ * it and whether it is linked. A delivery made for it lands only while the
+ * same attach holds the tap.
+ */
+export interface TapGeneration {
+  readonly generation: number;
+  readonly linked: boolean;
 }
 
 /**
@@ -13,14 +30,24 @@ interface TapEntry<TClient> {
 export class TapRegistry<TClient> {
   private readonly bySession = new Map<SessionID, TapEntry<TClient>>();
 
+  private nextGeneration = 0;
+
   /**
    * Makes the client the session's tap and returns the client it displaced,
-   * or null when there was none or it is the same connection.
+   * or null when there was none or it is the same connection. A linked tap
+   * also takes the messages held under the session's agent session id.
    */
-  attach(sessionID: SessionID, client: TClient): TClient | null {
+  attach(sessionID: SessionID, client: TClient, linked = true): TClient | null {
     const previous = this.bySession.get(sessionID)?.client ?? null;
 
-    this.bySession.set(sessionID, { client, claimed: new Set() });
+    this.nextGeneration += 1;
+
+    this.bySession.set(sessionID, {
+      client,
+      claimed: new Set(),
+      linked,
+      generation: this.nextGeneration,
+    });
 
     return previous === client ? null : previous;
   }
@@ -45,6 +72,12 @@ export class TapRegistry<TClient> {
     return previous;
   }
 
+  findTap(sessionID: SessionID): TapGeneration | null {
+    const entry = this.bySession.get(sessionID);
+
+    return entry === undefined ? null : { generation: entry.generation, linked: entry.linked };
+  }
+
   hasTap(sessionID: SessionID): boolean {
     return this.bySession.has(sessionID);
   }
@@ -53,10 +86,15 @@ export class TapRegistry<TClient> {
     return this.bySession.get(sessionID)?.client === client;
   }
 
-  claimDelivery(sessionID: SessionID, messageID: MessageID): TClient | null {
+  /**
+   * Claims the message for the session's tap and returns its client, or
+   * null when the tap already took it or another attach replaced the tap
+   * the delivery was made for.
+   */
+  claimDelivery(sessionID: SessionID, messageID: MessageID, generation: number): TClient | null {
     const entry = this.bySession.get(sessionID);
 
-    if (entry === undefined || entry.claimed.has(messageID)) {
+    if (entry === undefined || entry.generation !== generation || entry.claimed.has(messageID)) {
       return null;
     }