@intx/hub-sessions 0.1.2

package/src/agent-state-kind.test.ts

@@ -0,0 +1,247 @@
+import { describe, test, expect } from "bun:test";
+import {
+  agentStateAuthorize,
+  agentStateKindHandler,
+  AGENT_STATE_DEPLOY_REF,
+} from "./agent-state-kind";
+import type { Principal, RepoId } from "./repo-store";
+
+describe("agentStateKindHandler metadata", () => {
+  test("declares the agent-state kind and agents directory prefix", () => {
+    expect(agentStateKindHandler.kind).toBe("agent-state");
+    expect(agentStateKindHandler.directoryPrefix).toBe("agents");
+  });
+});
+
+describe("agentStateAuthorize", () => {
+  const REPO: RepoId = { kind: "agent-state", id: "agent-1" };
+  const OTHER_REPO: RepoId = { kind: "agent-state", id: "agent-2" };
+  const STATE_REF = "refs/heads/state";
+
+  function farFuture(): number {
+    return Date.now() + 60_000;
+  }
+
+  function userPrincipal(
+    overrides: {
+      effect?: "allow" | "deny";
+      resource?: string;
+      grantVerb?: string;
+      refPattern?: string;
+      actions?: string[];
+      expiresAt?: number;
+    } = {},
+  ): Principal {
+    return {
+      kind: "user",
+      principalId: "user-1",
+      tenantId: "tenant-1",
+      authz: {
+        effect: overrides.effect ?? "allow",
+        resource: overrides.resource ?? "agent-state:agent-1",
+        grantVerb: overrides.grantVerb ?? "read",
+      },
+      tokenClaims: {
+        refPattern: overrides.refPattern ?? "refs/heads/**",
+        actions: overrides.actions ?? ["createPack", "resolveRef"],
+        expiresAt: overrides.expiresAt ?? farFuture(),
+      },
+    } as Principal;
+  }
+
+  test("hub principal: allowed for any action (regression)", () => {
+    for (const action of [
+      "init",
+      "writeTree",
+      "receivePack",
+      "createPack",
+      "resolveRef",
+    ] as const) {
+      const r = agentStateAuthorize(
+        { kind: "hub" } as Principal,
+        REPO,
+        STATE_REF,
+        action,
+      );
+      expect(r.allowed).toBe(true);
+    }
+  });
+
+  test("sidecar principal: receivePack allowed on its own repo (regression)", () => {
+    const sidecar = { kind: "sidecar", agentId: "agent-1" } as Principal;
+    const r = agentStateAuthorize(sidecar, REPO, STATE_REF, "receivePack");
+    expect(r.allowed).toBe(true);
+  });
+
+  test("sidecar principal: createPack / resolveRef on deploy ref allowed (regression)", () => {
+    const sidecar = { kind: "sidecar", agentId: "agent-1" } as Principal;
+    expect(
+      agentStateAuthorize(sidecar, REPO, AGENT_STATE_DEPLOY_REF, "createPack")
+        .allowed,
+    ).toBe(true);
+    expect(
+      agentStateAuthorize(sidecar, REPO, AGENT_STATE_DEPLOY_REF, "resolveRef")
+        .allowed,
+    ).toBe(true);
+  });
+
+  test("sidecar principal: createPack on non-deploy ref denied (regression)", () => {
+    const sidecar = { kind: "sidecar", agentId: "agent-1" } as Principal;
+    const r = agentStateAuthorize(sidecar, REPO, STATE_REF, "createPack");
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/sidecar may only fetch/);
+  });
+
+  test("sidecar principal: cannot access another sidecar's repo (regression)", () => {
+    const sidecar = { kind: "sidecar", agentId: "agent-1" } as Principal;
+    const r = agentStateAuthorize(
+      sidecar,
+      OTHER_REPO,
+      STATE_REF,
+      "receivePack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/cannot access/);
+  });
+
+  test("sidecar principal: writeTree denied (regression)", () => {
+    const sidecar = { kind: "sidecar", agentId: "agent-1" } as Principal;
+    const r = agentStateAuthorize(sidecar, REPO, STATE_REF, "writeTree");
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/hub-only/);
+  });
+
+  test("user principal: allowed when claims and verdict agree", () => {
+    const r = agentStateAuthorize(
+      userPrincipal(),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(true);
+  });
+
+  test("user principal: denied for non-agent-state repo", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ resource: "asset:asset-1" }),
+      { kind: "skill", id: "asset-1" },
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/non-agent-state repo/);
+  });
+
+  test("user principal: malformed principal is denied with structural reason", () => {
+    const badPrincipal = {
+      kind: "user",
+      principalId: "user-1",
+      // missing tenantId, authz, tokenClaims
+    } as Principal;
+    const r = agentStateAuthorize(badPrincipal, REPO, STATE_REF, "createPack");
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/user principal is malformed/);
+  });
+
+  test("user principal: denied when tokenClaims.actions does not include the requested action", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ actions: ["resolveRef"] }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/token does not grant action createPack/);
+  });
+
+  test("user principal: denied when refPattern does not match the requested ref", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ refPattern: "refs/heads/release-*" }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/refPattern .* does not match/);
+  });
+
+  test("user principal: denied when the token is expired", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ expiresAt: Date.now() - 1 }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/token expired/);
+  });
+
+  test("user principal: denied when verdict.resource does not target this repo (sanity drift)", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ resource: "agent-state:agent-other" }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/authz verdict resource .* does not match/);
+  });
+
+  test("user principal: denied when verdict.resource has the wrong kind prefix (sanity drift)", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ resource: "asset:agent-1" }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/authz verdict resource .* does not match/);
+  });
+
+  test("user principal: denied when verdict.grantVerb does not match the action's verb (sanity drift)", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ grantVerb: "write" }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/authz verdict grantVerb .* does not match/);
+  });
+
+  test("user principal: denied when verdict effect is deny even though all sanity checks pass", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({ effect: "deny" }),
+      REPO,
+      STATE_REF,
+      "createPack",
+    );
+    expect(r.allowed).toBe(false);
+    if (r.allowed) throw new Error("unreachable");
+    expect(r.reason).toMatch(/authz verdict denied/);
+  });
+
+  test("user principal: write action requires write grantVerb and matching claims", () => {
+    const r = agentStateAuthorize(
+      userPrincipal({
+        actions: ["receivePack"],
+        grantVerb: "write",
+      }),
+      REPO,
+      STATE_REF,
+      "receivePack",
+    );
+    expect(r.allowed).toBe(true);
+  });
+});

package/src/agent-state-kind.ts

@@ -0,0 +1,204 @@
+import { type } from "arktype";
+import { glob, repoActionToGrantVerb } from "@intx/hub-common";
+import {
+  UserPrincipal,
+  type AuthorizeFn,
+  type KindHandler,
+  type Principal,
+  type ValidatePushResult,
+} from "./repo-store";
+
+export type AgentStateHubPrincipal = { readonly kind: "hub" };
+
+export type AgentStateSidecarPrincipal = {
+  readonly kind: "sidecar";
+  readonly agentId: string;
+};
+
+export type AgentStatePrincipal =
+  | AgentStateHubPrincipal
+  | AgentStateSidecarPrincipal;
+
+const SidecarPrincipal = type({
+  kind: "'sidecar'",
+  agentId: "string",
+});
+
+export const AGENT_STATE_DEPLOY_REF = "refs/heads/deploy";
+
+const ALLOWED_STATE_TOP_LEVEL = new Set([
+  "state",
+  ".gitignore",
+  "turns.jsonl",
+  "prompt.jsonl",
+  "response.jsonl",
+  "manifest.jsonl",
+  "metadata.json",
+  "tool-output",
+]);
+
+const ALLOWED_DEPLOY_TOP_LEVEL = new Set(["deploy", ".gitignore"]);
+
+export const agentStateKindHandler: KindHandler = {
+  kind: "agent-state",
+  directoryPrefix: "agents",
+  validatePush: ({ ref, topLevelTreePaths }): ValidatePushResult => {
+    // The deploy ref carries hub-authored prompt content under
+    // `deploy/`; every other ref carries sidecar-pushed agent state
+    // and must stay confined to the state-bearing allowlist.
+    const allowed =
+      ref === AGENT_STATE_DEPLOY_REF
+        ? ALLOWED_DEPLOY_TOP_LEVEL
+        : ALLOWED_STATE_TOP_LEVEL;
+    const offender = topLevelTreePaths.find((p) => !allowed.has(p));
+    if (offender !== undefined) {
+      return {
+        ok: false,
+        reason: `tree contains disallowed top-level path: ${offender}`,
+      };
+    }
+    if (!topLevelTreePaths.some((p) => p !== ".gitignore")) {
+      return {
+        ok: false,
+        reason: "tree must include at least one state-bearing top-level entry",
+      };
+    }
+    return { ok: true };
+  },
+  onRefUpdated: () => {
+    // No consumer at this kind today; the substrate's hook surface is
+    // uniform across kinds and future kinds will use it.
+  },
+};
+
+export const agentStateAuthorize: AuthorizeFn = (
+  principal: Principal,
+  repoId,
+  ref,
+  action,
+) => {
+  if (principal.kind === "hub") {
+    // Full access at this kind. Hub-side reads (getDeployRef,
+    // createDeployPack) and writes (writeDeployTree) all flow through
+    // here, so changing this branch tightens behavior in non-obvious
+    // places.
+    return { allowed: true };
+  }
+
+  if (principal.kind === "sidecar") {
+    const parsed = SidecarPrincipal(principal);
+    if (parsed instanceof type.errors) {
+      return {
+        allowed: false,
+        reason: `sidecar principal is malformed: ${parsed.summary}`,
+      };
+    }
+    if (repoId.kind !== "agent-state" || repoId.id !== parsed.agentId) {
+      return {
+        allowed: false,
+        reason: `sidecar ${parsed.agentId} cannot access ${repoId.kind}/${repoId.id}`,
+      };
+    }
+    switch (action) {
+      case "receivePack":
+      case "resolveRef":
+        return { allowed: true };
+      case "createPack":
+        if (ref !== AGENT_STATE_DEPLOY_REF) {
+          return {
+            allowed: false,
+            reason: `sidecar may only fetch ${AGENT_STATE_DEPLOY_REF}, not ${ref}`,
+          };
+        }
+        return { allowed: true };
+      case "init":
+        return {
+          allowed: false,
+          reason: "init is not authorize-gated for agent-state",
+        };
+      case "writeTree":
+        return {
+          allowed: false,
+          reason: `action ${action} is hub-only for agent-state`,
+        };
+      default: {
+        const _exhaustive: never = action;
+        return {
+          allowed: false,
+          reason: `unhandled action: ${String(_exhaustive)}`,
+        };
+      }
+    }
+  }
+
+  if (principal.kind === "user") {
+    // The route layer has already pre-resolved the grant verdict and
+    // attached it as `authz`. The substrate does NOT re-query the
+    // grant store here; it (a) checks the bearer-token's claims
+    // bound the requested (ref, action) and have not expired, and
+    // (b) sanity-checks that the pre-resolved verdict targets this
+    // exact resource and grant verb. Both gates must pass before the
+    // verdict's `effect` is honoured.
+    const parsed = UserPrincipal(principal);
+    if (parsed instanceof type.errors) {
+      return {
+        allowed: false,
+        reason: `user principal is malformed: ${parsed.summary}`,
+      };
+    }
+    if (repoId.kind !== "agent-state") {
+      return {
+        allowed: false,
+        reason: `user authorize received non-agent-state repo ${repoId.kind}/${repoId.id}`,
+      };
+    }
+    if (!parsed.tokenClaims.actions.includes(action)) {
+      return {
+        allowed: false,
+        reason: `token does not grant action ${action}`,
+      };
+    }
+    // `ref === "*"` is the substrate's sentinel for the bulk read
+    // performed by `listRefs`. Per-ref filtering is the advertise-refs
+    // layer's responsibility, so the bulk read is gated on action and
+    // expiry alone.
+    if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
+      return {
+        allowed: false,
+        reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
+      };
+    }
+    if (Date.now() >= parsed.tokenClaims.expiresAt) {
+      return {
+        allowed: false,
+        reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
+      };
+    }
+    const expectedResource = `agent-state:${repoId.id}`;
+    if (parsed.authz.resource !== expectedResource) {
+      return {
+        allowed: false,
+        reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
+      };
+    }
+    const expectedGrantVerb = repoActionToGrantVerb(action);
+    if (parsed.authz.grantVerb !== expectedGrantVerb) {
+      return {
+        allowed: false,
+        reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
+      };
+    }
+    if (parsed.authz.effect === "allow") {
+      return { allowed: true };
+    }
+    return {
+      allowed: false,
+      reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
+    };
+  }
+
+  return {
+    allowed: false,
+    reason: `unknown principal kind: ${principal.kind}`,
+  };
+};