@intx/hub-sessions 0.1.2 → 0.3.0

package/src/repo-store/store.ts

@@ -1,428 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import git from "isomorphic-git";
-import { createSSHSignature } from "@intx/crypto-node";
-import {
-  initRepo as storageInitRepo,
-  createDeployPack,
-  receivePackObjects,
-  type CommitSigner,
-} from "@intx/storage-isogit";
-import { hasCode } from "@intx/types";
-import { getLogger } from "@intx/log";
-import type {
-  AuthorizeFn,
-  InitRepoOpts,
-  KindHandler,
-  Principal,
-  RefEntry,
-  RepoAction,
-  RepoId,
-  RepoKind,
-  RepoStore,
-  TreeContent,
-} from "./types";
-import { SAFE_REPO_ID } from "./types";
-
-const AUTHOR = {
-  name: "interchange-hub",
-  email: "hub@interchange.local",
-};
-
-const logger = getLogger(["hub", "repo-store"]);
-
-type SigningKey = { privateKey: Uint8Array; publicKey: Uint8Array };
-
-/**
- * In-process push-serialization lock. Keyed by `${kind}/${id}`. Each
- * entry holds the tail of the chain of in-flight critical sections for
- * that repo; the next acquirer awaits the current tail and replaces it
- * with its own pending completion. On release the tail-check
- * (`if (locks.get(key) === myTail) locks.delete(key)`) prevents the map
- * from leaking entries once the chain drains.
- *
- * Single-process assumption: this protects against concurrent operations
- * inside a single hub instance. Cross-process serialization (e.g. a
- * second hub replica or an external git client touching the same
- * on-disk repo) would need a filesystem-backed lock; the migration path
- * is to swap the body of `withRepoLock` for an FS-lock acquire/release
- * around the same critical section.
- */
-const locks = new Map<string, Promise<void>>();
-
-async function withRepoLock<T>(
-  repoId: RepoId,
-  fn: () => Promise<T>,
-): Promise<T> {
-  const key = `${repoId.kind}/${repoId.id}`;
-  const previous = locks.get(key) ?? Promise.resolve();
-  let releaseFn: () => void = () => undefined;
-  const tail = new Promise<void>((resolve) => {
-    releaseFn = resolve;
-  });
-  locks.set(key, tail);
-  try {
-    await previous;
-    return await fn();
-  } finally {
-    if (locks.get(key) === tail) {
-      locks.delete(key);
-    }
-    releaseFn();
-  }
-}
-
-export type CreateRepoStoreConfig = {
-  dataDir: string;
-  signingKey: SigningKey;
-  /**
-   * Handler map keyed by repo kind. The substrate throws at request
-   * time when a kind has no registered handler, so callers may omit
-   * kinds they do not service (e.g. a per-asset-kind store that only
-   * registers `skill`).
-   */
-  handlers: Partial<Record<RepoKind, KindHandler>>;
-  authorize: AuthorizeFn;
-  /**
-   * Optional per-repo signing callback. When supplied and the callback
-   * returns a `CommitSigner` for the given `repoId`, the substrate
-   * passes that signer to `initRepo` so the genesis commit is authored
-   * as `interchange-hub` and signed. When the callback returns
-   * `undefined`, or the field is omitted entirely, the substrate falls
-   * back to the unsigned harness-authored genesis.
-   */
-  signingCallback?: (repoId: RepoId) => CommitSigner | undefined;
-};
-
-export function createRepoStore(config: CreateRepoStoreConfig): RepoStore {
-  const { dataDir, signingKey, handlers, authorize, signingCallback } = config;
-
-  function handlerFor(repoId: RepoId): KindHandler {
-    const handler = handlers[repoId.kind];
-    if (handler === undefined) {
-      throw new Error(`no handler registered for kind: ${repoId.kind}`);
-    }
-    return handler;
-  }
-
-  function signerFor(repoId: RepoId): CommitSigner | undefined {
-    return signingCallback === undefined ? undefined : signingCallback(repoId);
-  }
-
-  function repoDir(repoId: RepoId): string {
-    if (!SAFE_REPO_ID.test(repoId.id)) {
-      throw new Error(`repo_id_invalid: ${repoId.id}`);
-    }
-    const handler = handlerFor(repoId);
-    return path.join(dataDir, handler.directoryPrefix, repoId.id);
-  }
-
-  function gateAccess(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-    action: RepoAction,
-  ): void {
-    const verdict = authorize(principal, repoId, ref, action);
-    if (!verdict.allowed) {
-      throw new Error(`authorize_denied: ${verdict.reason}`);
-    }
-  }
-
-  function validateClearPrefix(clearPrefix: string): void {
-    const malformed =
-      clearPrefix.length === 0 ||
-      !clearPrefix.endsWith("/") ||
-      clearPrefix.startsWith("/") ||
-      clearPrefix.split("/").includes("..");
-    if (malformed) {
-      throw new Error(`clear_prefix_invalid: ${clearPrefix}`);
-    }
-  }
-
-  function storageOptsFor(
-    repoId: RepoId,
-    opts: InitRepoOpts | undefined,
-  ): { signer?: CommitSigner; gitignore?: string } {
-    const out: { signer?: CommitSigner; gitignore?: string } = {};
-    const signer = signerFor(repoId);
-    if (signer !== undefined) out.signer = signer;
-    if (opts?.gitignore !== undefined) out.gitignore = opts.gitignore;
-    return out;
-  }
-
-  async function initRepo(repoId: RepoId, opts?: InitRepoOpts): Promise<void> {
-    await storageInitRepo(repoDir(repoId), storageOptsFor(repoId, opts));
-  }
-
-  function getRepoDir(repoId: RepoId): string {
-    return repoDir(repoId);
-  }
-
-  async function listRefs(
-    principal: Principal,
-    repoId: RepoId,
-  ): Promise<RefEntry[]> {
-    gateAccess(principal, repoId, "*", "resolveRef");
-    const dir = repoDir(repoId);
-    const repoExists = await fs.promises
-      .stat(path.join(dir, ".git"))
-      .then(() => true)
-      .catch(() => false);
-    if (!repoExists) return [];
-
-    const [branches, tags] = await Promise.all([
-      git.listBranches({ fs, dir }),
-      git.listTags({ fs, dir }),
-    ]);
-
-    const names: string[] = [];
-    for (const b of branches) names.push(`refs/heads/${b}`);
-    for (const t of tags) names.push(`refs/tags/${t}`);
-    names.sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
-
-    const entries: RefEntry[] = [];
-    for (const name of names) {
-      try {
-        const sha = await git.resolveRef({ fs, dir, ref: name });
-        entries.push({ name, sha });
-      } catch (err: unknown) {
-        if (hasCode(err) && err.code === "NotFoundError") continue;
-        throw err;
-      }
-    }
-    return entries;
-  }
-
-  async function resolveHead(
-    principal: Principal,
-    repoId: RepoId,
-  ): Promise<{ symbolicTarget: string; sha: string } | null> {
-    gateAccess(principal, repoId, "*", "resolveRef");
-    const dir = repoDir(repoId);
-    const repoExists = await fs.promises
-      .stat(path.join(dir, ".git"))
-      .then(() => true)
-      .catch(() => false);
-    if (!repoExists) return null;
-
-    const symbolicTarget = await git.currentBranch({ fs, dir, fullname: true });
-    if (symbolicTarget === undefined) return null;
-
-    const sha = await resolveRefSha(dir, symbolicTarget);
-    if (sha === null) return null;
-
-    return { symbolicTarget, sha };
-  }
-
-  async function resolveRefSha(
-    dir: string,
-    ref: string,
-  ): Promise<string | null> {
-    try {
-      return await git.resolveRef({ fs, dir, ref });
-    } catch (err: unknown) {
-      if (hasCode(err) && err.code === "NotFoundError") {
-        return null;
-      }
-      throw err;
-    }
-  }
-
-  async function clearIndexPrefix(dir: string, prefix: string): Promise<void> {
-    const matrix = await git.statusMatrix({ fs, dir });
-    for (const row of matrix) {
-      const filepath = row[0];
-      if (filepath.startsWith(prefix)) {
-        await git.remove({ fs, dir, filepath });
-      }
-    }
-  }
-
-  async function writeFileEntry(
-    dir: string,
-    relPath: string,
-    contents: string | Uint8Array,
-  ): Promise<void> {
-    const fullPath = path.join(dir, relPath);
-    await fs.promises.mkdir(path.dirname(fullPath), { recursive: true });
-    await fs.promises.writeFile(fullPath, contents);
-    await git.add({ fs, dir, filepath: relPath });
-  }
-
-  async function writeTree(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-    content: TreeContent,
-  ): Promise<{ commitSha: string }> {
-    gateAccess(principal, repoId, ref, "writeTree");
-
-    // The lock spans the entire substrate body of writeTree: index
-    // mutation, validatePush, commit, and the onRefUpdated hook. Holding
-    // the lock through onRefUpdated keeps post-update consumers
-    // serialized against the same ref's next writer.
-    return withRepoLock(repoId, async () => {
-      const dir = repoDir(repoId);
-      await storageInitRepo(dir, storageOptsFor(repoId, undefined));
-
-      const handler = handlerFor(repoId);
-
-      if (content.clearPrefix !== undefined) {
-        validateClearPrefix(content.clearPrefix);
-        await clearIndexPrefix(dir, content.clearPrefix);
-        await fs.promises.rm(path.join(dir, content.clearPrefix), {
-          recursive: true,
-          force: true,
-        });
-      }
-
-      for (const [relPath, contents] of Object.entries(content.files)) {
-        await writeFileEntry(dir, relPath, contents);
-      }
-
-      const topLevelTreePaths = Array.from(
-        new Set(
-          Object.keys(content.files).map((p) => {
-            const slash = p.indexOf("/");
-            return slash === -1 ? p : p.substring(0, slash);
-          }),
-        ),
-      );
-      const readBlob = async (relPath: string): Promise<Uint8Array> => {
-        const entry = content.files[relPath];
-        if (entry === undefined) {
-          throw new Error(
-            `readBlob: path ${relPath} not present in tree content`,
-          );
-        }
-        if (typeof entry === "string") {
-          return new TextEncoder().encode(entry);
-        }
-        return entry;
-      };
-      const validation = await handler.validatePush({
-        repoId,
-        ref,
-        topLevelTreePaths,
-        readBlob,
-      });
-      if (!validation.ok) {
-        throw new Error(`path_violation: ${validation.reason}`);
-      }
-
-      // Resolve the previous ref value for the post-update hook (precise:
-      // null only when the ref truly doesn't exist) and the parent SHA for
-      // the new commit (best-effort: any error falls back to HEAD, so a
-      // first write on a never-touched ref produces a commit parented on
-      // the repo's initial commit instead of failing).
-      const oldSha = await resolveRefSha(dir, ref);
-      let parentSha: string;
-      try {
-        parentSha = await git.resolveRef({ fs, dir, ref });
-      } catch {
-        parentSha = await git.resolveRef({ fs, dir, ref: "HEAD" });
-      }
-
-      const commitSha = await git.commit({
-        fs,
-        dir,
-        message: content.message,
-        author: AUTHOR,
-        parent: [parentSha],
-        ref,
-        signingKey: "sshsig",
-        onSign: async ({ payload }) => ({
-          signature: createSSHSignature(
-            payload,
-            signingKey.privateKey,
-            signingKey.publicKey,
-          ),
-        }),
-      });
-
-      await handler.onRefUpdated({ repoId, ref, oldSha, newSha: commitSha });
-
-      return { commitSha };
-    });
-  }
-
-  async function receivePack(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-    pack: Uint8Array,
-    commitSha: string,
-    expectedOldSha: string | null,
-  ): Promise<void> {
-    gateAccess(principal, repoId, ref, "receivePack");
-
-    // The lock spans the entire substrate body of receivePack: the
-    // packfile index, the CAS check against `expectedOldSha`, the
-    // validateTree hook, the ref write, and the onRefUpdated hook.
-    // `oldSha` for onRefUpdated is taken from the receivePackObjects
-    // return value so the post-update hook sees the same pre-image the
-    // CAS read observed, without a second resolveRef.
-    return withRepoLock(repoId, async () => {
-      const dir = repoDir(repoId);
-      await storageInitRepo(dir, storageOptsFor(repoId, undefined));
-
-      const handler = handlerFor(repoId);
-      const transferId = crypto.randomUUID().replace(/-/g, "");
-
-      const oldSha = await receivePackObjects(
-        dir,
-        pack,
-        ref,
-        commitSha,
-        transferId,
-        expectedOldSha,
-        async (paths, readBlob) => {
-          const result = await handler.validatePush({
-            repoId,
-            ref,
-            topLevelTreePaths: paths,
-            readBlob,
-          });
-          if (!result.ok) {
-            logger.debug`validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${result.reason}`;
-            return { ok: false, reason: result.reason };
-          }
-          return true;
-        },
-      );
-
-      await handler.onRefUpdated({ repoId, ref, oldSha, newSha: commitSha });
-    });
-  }
-
-  async function createPack(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-  ): Promise<{ pack: Uint8Array; commitSha: string; ref: string }> {
-    gateAccess(principal, repoId, ref, "createPack");
-    const { pack, commitSha } = await createDeployPack(repoDir(repoId), ref);
-    return { pack, commitSha, ref };
-  }
-
-  async function resolveRef(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-  ): Promise<string | null> {
-    gateAccess(principal, repoId, ref, "resolveRef");
-    return resolveRefSha(repoDir(repoId), ref);
-  }
-
-  return {
-    initRepo,
-    writeTree,
-    receivePack,
-    createPack,
-    resolveRef,
-    listRefs,
-    resolveHead,
-    getRepoDir,
-  };
-}

package/src/repo-store/types.ts

@@ -1,253 +0,0 @@
-import { type } from "arktype";
-import { RepoAction as RepoActionSchema } from "@intx/types/sidecar";
-import type { RepoKind, RepoId, RepoAction } from "@intx/types/sidecar";
-
-export type { RepoKind, RepoId, RepoAction };
-
-/**
- * arktype validator for the `user` principal variant. The substrate
- * only requires the `kind` discriminant; kind handlers that accept
- * user-token-authenticated requests rely on this shape to
- * cross-check the pre-resolved authz verdict against the bearer
- * token's claims. The validator is exported alongside the type so
- * handlers can call it for a structural narrow without re-declaring
- * the shape.
- *
- * Field semantics:
- *   - `authz`: the pre-resolved grant verdict from the route layer.
- *     The kind handler does NOT re-query the grant store; it only
- *     sanity-checks that the verdict targets the right resource and
- *     grant verb, then defers to `effect`.
- *   - `tokenClaims`: the bearer-token's scope. The kind handler
- *     verifies the requested `(ref, action)` falls inside this scope
- *     synchronously (`actions.includes(action)`,
- *     `glob.match(refPattern, ref)`, `Date.now() < expiresAt`).
- */
-export const UserPrincipal = type({
-  kind: "'user'",
-  principalId: "string",
-  tenantId: "string",
-  authz: {
-    effect: "'allow' | 'deny'",
-    resource: "string",
-    grantVerb: "string",
-  },
-  tokenClaims: {
-    refPattern: "string",
-    actions: RepoActionSchema.array(),
-    expiresAt: "number",
-  },
-});
-
-export type UserPrincipal = typeof UserPrincipal.infer;
-
-/**
- * Regex defining the shape of a valid `RepoId.id`. The substrate
- * validates against this at every public operation and throws an Error
- * prefixed with `"repo_id_invalid: "` on mismatch.
- */
-export const SAFE_REPO_ID = /^[a-zA-Z0-9_-]+$/;
-
-/**
- * Principal is a discriminated-union extension point. The substrate
- * requires only the `kind` discriminant; concrete principal shapes live
- * in kind-handler packages and are narrowed via `principal.kind === "..."`
- * checks plus arktype validation in the handler. No index signature is
- * declared here so that handlers do not need `as Type` casts to access
- * their own fields.
- */
-export type Principal = { readonly kind: string };
-
-/**
- * Authorization callback supplied to the repo-store. Called once per
- * substrate operation that requires gating (`writeTree`, `receivePack`,
- * `createPack`, `resolveRef`, plus the bulk-read variants below). The
- * substrate translates an `allowed: false` verdict into a thrown Error
- * prefixed with `"authorize_denied: "` carrying the supplied reason.
- *
- * The substrate passes the literal string `"*"` as `ref` when it calls
- * the authorize hook on behalf of the bulk-read methods `listRefs` and
- * `resolveHead`. Both methods enumerate refs across the whole repo and
- * have no single ref to feed into a per-ref claim check; the sentinel
- * lets kind handlers recognise the call and skip the per-ref
- * `refPattern` match while still gating on `action` (always
- * `"resolveRef"` for the bulk case) and expiry. Per-ref refPattern
- * filtering for the response payload is the responsibility of the
- * caller (the advertise-refs layer), not the authorize hook.
- */
-export type AuthorizeFn = (
-  principal: Principal,
-  repoId: RepoId,
-  ref: string,
-  action: RepoAction,
-) => { allowed: true } | { allowed: false; reason: string };
-
-export type ValidatePushResult = { ok: true } | { ok: false; reason: string };
-
-/**
- * Per-call options for `initRepo`. Currently a single override —
- * `gitignore` — that overrides the body written to `.gitignore` in
- * the genesis tree. When omitted, the substrate's default body is
- * used. The asset REST handler supplies a richer body that includes
- * OS/editor cruft, common build output, and `keys/`.
- */
-export type InitRepoOpts = {
-  gitignore?: string;
-};
-
-/**
- * A single ref entry returned by `RepoStore.listRefs`. `name` is the
- * fully-qualified ref name (`refs/heads/main`, `refs/tags/v1`, ...);
- * `sha` is the SHA-1 the ref currently resolves to.
- */
-export type RefEntry = {
-  readonly name: string;
-  readonly sha: string;
-};
-
-export type TreeContent = {
-  /**
-   * Map of repo-relative path to file contents. Each entry is written
-   * to the working tree and staged before commit.
-   */
-  files: Record<string, string | Uint8Array>;
-  /**
-   * Optional directory-subtree prefix to clear before staging. When
-   * set, every tracked path beginning with this prefix is removed
-   * from the git index and the corresponding directory on disk is
-   * deleted before `files` is written. Must end with `/` and must
-   * not contain `..` or absolute path components. When unset,
-   * writeTree is purely additive.
-   */
-  clearPrefix?: string;
-  /** Commit message for the resulting commit. */
-  message: string;
-};
-
-export interface KindHandler {
-  kind: RepoKind;
-  /**
-   * On-disk directory under `dataDir` for repos of this kind. Allows
-   * each kind to declare its own layout (e.g. "agents") so the
-   * substrate does not hard-code a `<kind>/<id>` path.
-   */
-  directoryPrefix: string;
-  /**
-   * Inspect the prospective commit's tree before the ref is
-   * advanced. Return `{ ok: false, reason }` to reject the write.
-   * The substrate translates rejection into a thrown Error whose
-   * message begins with `"path_violation: "`.
-   *
-   * Runs on every `receivePack` and every `writeTree` independently
-   * of the authorize verdict: authorize gates access, validatePush
-   * enforces content rules.
-   *
-   * `topLevelTreePaths` lists the names directly under the tree
-   * root. `readBlob` reads any blob in the tree by repo-root-relative
-   * POSIX path (e.g. `greet/SKILL.md`). Handlers that only need
-   * path-level checks can ignore `readBlob`.
-   */
-  validatePush: (args: {
-    repoId: RepoId;
-    ref: string;
-    topLevelTreePaths: string[];
-    readBlob: (path: string) => Promise<Uint8Array>;
-  }) => Promise<ValidatePushResult> | ValidatePushResult;
-  /**
-   * Fired after a successful ref update from any operation. `oldSha`
-   * is `null` when the ref did not exist before the update.
-   */
-  onRefUpdated: (args: {
-    repoId: RepoId;
-    ref: string;
-    oldSha: string | null;
-    newSha: string;
-  }) => Promise<void> | void;
-}
-
-export interface RepoStore {
-  /**
-   * Bookkeeping primitive. Idempotent. Creates the repo directory
-   * and initializes git when not already present. Not gated by
-   * `authorize`: the only state it can produce is an empty repo, so
-   * the higher-level question of who may mint a new `<kind>/<id>`
-   * lives at the caller. The substrate also calls `initRepo`
-   * internally from `writeTree` and `receivePack`, so first-touch
-   * operations succeed without an explicit init call.
-   */
-  initRepo(repoId: RepoId, opts?: InitRepoOpts): Promise<void>;
-  writeTree(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-    content: TreeContent,
-  ): Promise<{ commitSha: string }>;
-  /**
-   * Receive a packfile and advance `ref` to `commitSha`.
-   *
-   * `expectedOldSha` is a compare-and-set guard the substrate runs
-   * under the per-repo lock. Pass a SHA string to require the ref
-   * currently points there; pass `null` to require the ref does not
-   * yet exist. On mismatch the call throws with a `non_fast_forward:`
-   * prefix and leaves the ref untouched.
-   *
-   * Callers that do not have the old SHA in hand should resolve it
-   * via `resolveRef` first; the substrate exposes no force-write
-   * mode because silently overwriting a losing concurrent update is
-   * never the right behavior.
-   */
-  receivePack(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-    pack: Uint8Array,
-    commitSha: string,
-    expectedOldSha: string | null,
-  ): Promise<void>;
-  createPack(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-  ): Promise<{ pack: Uint8Array; commitSha: string; ref: string }>;
-  resolveRef(
-    principal: Principal,
-    repoId: RepoId,
-    ref: string,
-  ): Promise<string | null>;
-  /**
-   * Enumerate the repo's refs (branches and tags), lexicographically
-   * sorted by name. The principal is gated under the same
-   * `resolveRef` action that `resolveRef` itself enforces — the
-   * substrate does not duplicate the check on a per-ref basis. When
-   * the on-disk repo does not yet exist (the bookkeeping primitive
-   * `initRepo` has never been called), the result is the empty list.
-   */
-  listRefs(principal: Principal, repoId: RepoId): Promise<RefEntry[]>;
-  /**
-   * Resolve HEAD into the ref it symbolically points at plus the SHA
-   * that ref currently resolves to. The principal is gated under the
-   * same `resolveRef` action that `resolveRef` and `listRefs`
-   * enforce. Returns `null` when:
-   *   - The on-disk repo does not yet exist (mirrors `listRefs`'s
-   *     empty-list contract for uninitialised repos).
-   *   - HEAD is detached (no symbolic target).
-   *   - HEAD's symbolic target does not resolve (unborn ref).
-   * The smart-HTTP advertise layer uses the result to emit
-   * `symref=HEAD:<target>` so stock `git clone` lands on a real
-   * branch instead of leaving the working tree unborn.
-   */
-  resolveHead(
-    principal: Principal,
-    repoId: RepoId,
-  ): Promise<{ symbolicTarget: string; sha: string } | null>;
-  /**
-   * Synchronously return the on-disk directory backing the repo.
-   * The path is the result of composing the substrate's `dataDir`,
-   * the kind handler's `directoryPrefix`, and the validated
-   * `repoId.id`. This carries no authorize gate: it is a pure path
-   * computation. Consumers of the path (the smart-HTTP wire
-   * handlers) remain authorize-gated through the substrate methods
-   * they reach into for ref-listing and pack negotiation.
-   */
-  getRepoDir(repoId: RepoId): string;
-}