@bevel-software/platform-core-backend 0.4.0 → 0.5.0

package/src/modules/groups/join-proposals.ts

@@ -0,0 +1,114 @@
+import {
+  KNOWN_VERBS,
+  parseAccessFile,
+  type ParsedEntry,
+  type Verb,
+} from '../access/access-control.service.js';
+
+/**
+ * What a join branch is PROPOSING, relative to the default branch.
+ *
+ * A join request is a change request whose branch edits one group's
+ * `access.md`. Rather than treating that change request as an all-or-nothing
+ * merge, the group's managers see its individual proposals — "grant Ali read",
+ * "grant GTM Team write" — and answer them one at a time. Approving a proposal
+ * writes THAT ONE grant onto the default branch through the ordinary access
+ * mutation path; the branch is never merged, so nothing else it happens to
+ * contain can ride along, and a change request naming five people can be
+ * answered with two yeses and three ignores.
+ *
+ * A proposal is any (principal, verb) GRANT the branch's copy of the file
+ * carries that the default branch's copy does not. Deliberately:
+ *
+ *  - grants only. A `deny` entry is not something to "accept", and a branch
+ *    that REMOVES an existing grant proposes nothing — it is a revocation,
+ *    which is not what this surface is for. Both are simply invisible here,
+ *    and both leave the branch as a normal change request in the review UI.
+ *  - every verb, not just `read`. A branch asking for `write` must be visible
+ *    AS a write request rather than hiding behind "asked to join"; and the
+ *    subset test that retires a request has to cover everything the file can
+ *    express, or a request proposing `write` would never settle.
+ *
+ * When the list comes back EMPTY the branch adds nothing the default branch
+ * does not already grant — its proposals have all been accepted (or were
+ * never anything) — and the change request has no reason to stay open.
+ */
+export interface JoinProposal {
+  verb: Verb;
+  /** Canonical identity — lowercased email, or canonical role name. */
+  id: string;
+  principal:
+    | { kind: 'user'; email: string; displayName: string }
+    | { kind: 'role'; role: string };
+  /** How to name this principal in the UI. */
+  label: string;
+}
+
+/** Canonical identity of an entry, for set comparison across the two files. */
+function identityOf(entry: ParsedEntry): string {
+  return entry.kind === 'user' ? `user:${entry.email}` : `role:${entry.role}`;
+}
+
+/**
+ * Folder rules from one copy of an `access.md`, per verb, grants only.
+ *
+ * A file that fails to parse yields NO grants. On the branch side that means
+ * a malformed proposal offers nothing to accept (fail-closed). On the default
+ * side it means every branch grant looks incoming — which is the safe
+ * direction too: the manager is shown proposals to consider rather than
+ * having them silently swallowed by an unreadable baseline.
+ */
+function grantsByVerb(text: string | null, path: string): Map<Verb, Map<string, ParsedEntry>> {
+  const out = new Map<Verb, Map<string, ParsedEntry>>();
+  for (const verb of KNOWN_VERBS) out.set(verb, new Map());
+  if (text === null) return out;
+  const parsed = parseAccessFile(text, path);
+  if (!parsed.ok) return out;
+  for (const verb of KNOWN_VERBS) {
+    const byId = out.get(verb)!;
+    for (const entry of parsed.file.entries[verb]) {
+      if (entry.deny) continue;
+      byId.set(identityOf(entry), entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * The grants `branchText` adds over `defaultText` — the proposals a manager
+ * can accept. Empty ⇒ the branch's rules are a subset of the default's.
+ *
+ * `path` is only used to label parse errors; both texts are the same file at
+ * two refs.
+ */
+export function pendingProposals(
+  branchText: string | null,
+  defaultText: string | null,
+  path: string,
+): JoinProposal[] {
+  const branch = grantsByVerb(branchText, path);
+  const base = grantsByVerb(defaultText, path);
+  const out: JoinProposal[] = [];
+  for (const verb of KNOWN_VERBS) {
+    const baseIds = base.get(verb)!;
+    for (const [id, entry] of branch.get(verb)!) {
+      if (baseIds.has(id)) continue;
+      out.push(
+        entry.kind === 'user'
+          ? {
+              verb,
+              id,
+              principal: { kind: 'user', email: entry.email, displayName: entry.displayName },
+              label: entry.displayName,
+            }
+          : {
+              verb,
+              id,
+              principal: { kind: 'role', role: entry.displayRole },
+              label: entry.displayRole,
+            },
+      );
+    }
+  }
+  return out;
+}

package/src/modules/groups/join-requests.service.ts

@@ -0,0 +1,185 @@
+import {
+  DEFAULT_BRANCH,
+  isJoinBranchFor,
+  type AuthUser,
+  type ChangeRequest,
+  type IWorkflowService,
+} from '@bevel-software/platform-shared';
+import { workspaceIdForBranch, type WorkspaceService } from '../workspace/workspace.service.js';
+import { pendingProposals, type JoinProposal } from './join-proposals.js';
+
+/** One open join change request, with what it still proposes. */
+export interface JoinRequest {
+  number: number;
+  branch: string;
+  requesterName: string;
+  createdAt: string;
+  /** Grants the branch adds over the default branch. Never empty (see below). */
+  proposals: JoinProposal[];
+}
+
+/**
+ * Join requests as PROPOSALS, and the reconciliation that retires them.
+ *
+ * The lifecycle has no state of its own — it is derived, every time, from two
+ * copies of one file:
+ *
+ *   open        the branch's `access.md` grants something the default's does not
+ *   settled     it does not
+ *
+ * so "approve" is not an operation on the request at all. A manager grants a
+ * principal through the ordinary access path (the same lock + commit every
+ * other access edit uses, gated the same way), the default branch gains that
+ * entry, and the proposal stops being pending because the diff no longer
+ * contains it. When the last one goes, the change request has nothing left to
+ * say and is rejected, its branch deleted.
+ *
+ * That reconciliation runs LAZILY on every listing as well as on demand, so a
+ * grant made anywhere — this banner, the Manage-access dialog, a hand edit —
+ * settles the request that asked for it. Nothing has to remember to.
+ */
+export class JoinRequestsService {
+  constructor(
+    private readonly workspaceService: WorkspaceService,
+    private readonly workflow: IWorkflowService,
+  ) {}
+
+  /**
+   * Open join requests for `group`, each carrying only its still-pending
+   * proposals. Requests with none left are reconciled away (rejected, branch
+   * deleted) and omitted.
+   *
+   * `actor` is who the reconciliation acts as — a manager of the group, since
+   * rejecting a change request requires write on everything it touches.
+   */
+  async list(
+    group: string,
+    folder: string,
+    crs: ChangeRequest[],
+    actor: AuthUser,
+  ): Promise<JoinRequest[]> {
+    await this.refresh();
+    const accessPath = `${folder}/access.md`;
+    const baseText = await this.readAt(DEFAULT_BRANCH, accessPath);
+    const out: JoinRequest[] = [];
+    for (const cr of crs) {
+      if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, group)) continue;
+      const proposals = pendingProposals(
+        await this.readAt(cr.branch, accessPath),
+        baseText,
+        accessPath,
+      );
+      if (proposals.length === 0) {
+        await this.settle(cr, actor);
+        continue;
+      }
+      out.push({
+        number: cr.number,
+        branch: cr.branch,
+        requesterName: cr.appAuthor?.name ?? 'Someone',
+        createdAt: cr.createdAt,
+        proposals,
+      });
+    }
+    return out.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+  }
+
+  /**
+   * Re-check ONE request and settle it if nothing is pending. Returns whether
+   * it was settled. Called right after a grant so the banner updates in the
+   * same round-trip instead of waiting for the next listing.
+   */
+  async reconcile(
+    group: string,
+    folder: string,
+    cr: ChangeRequest,
+    actor: AuthUser,
+  ): Promise<boolean> {
+    if (cr.state !== 'open' || !isJoinBranchFor(cr.branch, group)) return false;
+    await this.refresh();
+    const accessPath = `${folder}/access.md`;
+    const proposals = pendingProposals(
+      await this.readAt(cr.branch, accessPath),
+      await this.readAt(DEFAULT_BRANCH, accessPath),
+      accessPath,
+    );
+    if (proposals.length > 0) return false;
+    await this.settle(cr, actor);
+    return true;
+  }
+
+  /**
+   * Close a request whose proposals have all landed, and delete its branch.
+   *
+   * Rejecting rather than merging is the point: the grants are already on the
+   * default branch, so merging would replay a diff that is now empty of
+   * meaning while dragging along anything else the branch carries. The branch
+   * goes too — it exists only to hold a proposal that no longer exists.
+   *
+   * Best-effort by contract: this runs inside a listing, and a request that
+   * cannot be closed right now must not take the listing down with it. The
+   * next pass tries again.
+   */
+  private async settle(cr: ChangeRequest, actor: AuthUser): Promise<void> {
+    const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+    try {
+      await this.workflow.rejectChangeRequest(
+        cr.number,
+        actor,
+        cr.state,
+        cr.authorId ?? null,
+        cr.base,
+        wsId,
+      );
+    } catch (err) {
+      console.warn(
+        `[groups] could not close settled join request #${cr.number}: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+      return;
+    }
+    try {
+      await this.workflow.deleteBranch(wsId, cr.branch, actor);
+    } catch (err) {
+      // The request is closed either way; a leftover branch is cosmetic and
+      // the author can still delete it themselves.
+      console.warn(
+        `[groups] closed join request #${cr.number} but could not delete "${cr.branch}": ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+
+  /**
+   * The file at one branch, or null when it is absent/unreadable there.
+   *
+   * Every read runs against the DEFAULT branch's clone at `origin/<branch>`,
+   * so one workspace answers for every request and a join branch never needs
+   * a clone of its own. `readFileAtRef` takes a REPO-relative path (the KB
+   * dir is the repo root there).
+   */
+  private async readAt(branch: string, repoRelPath: string): Promise<string | null> {
+    try {
+      return await this.workspaceService.readFileAtRef(
+        workspaceIdForBranch(DEFAULT_BRANCH),
+        `origin/${branch}`,
+        repoRelPath,
+      );
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Refresh remote-tracking refs before reading them. Throttled inside, and
+   * best-effort: a request pushed seconds ago is worth one fetch, but a fetch
+   * failure must degrade to "read what we have" rather than empty the list.
+   */
+  private async refresh(): Promise<void> {
+    await this.workspaceService
+      .ensureRemotesFetched(workspaceIdForBranch(DEFAULT_BRANCH))
+      .catch(() => undefined);
+  }
+}

package/src/modules/secrets-vault/__tests__/oauth-return-to.route.test.ts

@@ -0,0 +1,283 @@
+import type { Server as HttpServer } from 'node:http';
+import { createHmac } from 'node:crypto';
+import express from 'express';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  createSecretsVaultRoutes,
+  createSecretsVaultPublicRoutes,
+  isSafeReturnPath,
+} from '../secrets-vault.routes.js';
+
+/**
+ * OAUTH `returnTo`: a sign-in started from a page other than /connect must land
+ * back on THAT page. The return path rides in the HMAC-signed `state` (field
+ * `r`) because the provider's callback arrives un-authenticated — the state is
+ * the only thing the callback can trust.
+ *
+ * The whole risk here is an open redirect: the callback concatenates `r` onto
+ * our own public origin and hands it to the browser as a `Location`. So the
+ * validation is pinned twice — as a unit table on `isSafeReturnPath`, and
+ * end-to-end on both the start route (what gets signed) and the callback (what
+ * gets redirected to, re-validated).
+ *
+ * Backward compatibility is the second thing under test: a start with NO body
+ * must produce exactly the state it produced before `returnTo` existed
+ * (`r: 'connect'`), and a legacy `'connect'` state must still land on /connect.
+ */
+
+const STATE_SECRET = 'test-secret';
+const FRONTEND = 'http://localhost:5173';
+const TOOL_PATH = 'Tools/weather.tool';
+const USER = 'user@x.com';
+const RETURN_TO = '/skills-and-tools/tools/weather';
+
+const toolManualService = {
+  listAccessible: async () => [
+    {
+      slug: 'weather',
+      name: 'weather',
+      path: TOOL_PATH,
+      type: 'mcp' as const,
+      variables: [
+        {
+          name: 'SIGNIN',
+          scope: 'user' as const,
+          label: 'Weather sign-in',
+          oauth: {
+            authorizationUrl: 'https://auth.example.com/authorize',
+            tokenUrl: 'https://auth.example.com/token',
+            clientId: 'client-1',
+          },
+        },
+      ],
+    },
+  ],
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['toolManualService'];
+
+const accessControl = {
+  canRead: async () => true,
+  canWrite: async () => false, // a plain reader may authorize their OWN account
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['accessControl'];
+
+const completeOAuth = vi.fn(async () => {});
+const secretsVault = {
+  beginToolOAuthByKey: async () => ({ id: 'secret-1', url: 'https://auth.example.com/authorize?client_id=client-1' }),
+  completeOAuth,
+} as unknown as Parameters<typeof createSecretsVaultRoutes>[0]['secretsVault'];
+
+const deps = {
+  secretsVault,
+  toolManualService,
+  accessControl,
+  stateSecret: STATE_SECRET,
+  publicBackendUrl: 'http://localhost:3000',
+  publicFrontendUrl: FRONTEND,
+};
+
+let httpServer: HttpServer | undefined;
+
+/** One server carrying BOTH routers, so a start's state can be replayed at the callback. */
+async function baseUrl(): Promise<string> {
+  const app = express();
+  app.use(express.json());
+  app.use('/api', createSecretsVaultPublicRoutes(deps)); // un-authed callback, mounted first
+  app.use((req, _res, next) => {
+    req.userId = `id-${USER}`;
+    req.userEmail = USER;
+    next();
+  });
+  app.use('/api', createSecretsVaultRoutes(deps));
+  httpServer = await new Promise<HttpServer>((resolve) => {
+    const s = app.listen(0, () => resolve(s));
+  });
+  const port = (httpServer.address() as { port: number }).port;
+  return `http://127.0.0.1:${port}`;
+}
+
+/** POST the start route with (or without) a body; return the signed `state` it put on the consent URL. */
+async function startAndReadState(base: string, body?: unknown): Promise<Record<string, unknown>> {
+  const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/start`, {
+    method: 'POST',
+    ...(body === undefined
+      ? {}
+      : { headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body) }),
+  });
+  expect(res.status).toBe(200);
+  const { url } = (await res.json()) as { url: string };
+  const state = new URL(url).searchParams.get('state')!;
+  expect(state).toBeTruthy();
+  return decodeState(state);
+}
+
+/** Decode a signed state's payload (the signature is verified by the callback tests). */
+function decodeState(token: string): Record<string, unknown> {
+  const [body] = token.split('.');
+  return JSON.parse(Buffer.from(body, 'base64url').toString()) as Record<string, unknown>;
+}
+
+/** Sign a state the way the routes do — used to drive the callback directly. */
+function signState(payload: Record<string, unknown>): string {
+  const body = Buffer.from(JSON.stringify({ iat: Date.now(), ...payload })).toString('base64url');
+  const sig = createHmac('sha256', STATE_SECRET).update(body).digest('base64url');
+  return `${body}.${sig}`;
+}
+
+/** Follow no redirects — the Location header IS the assertion. */
+async function callback(base: string, state: string): Promise<string> {
+  const res = await fetch(`${base}/api/secrets/oauth/callback?code=abc&state=${encodeURIComponent(state)}`, {
+    redirect: 'manual',
+  });
+  expect(res.status).toBe(302);
+  return res.headers.get('location')!;
+}
+
+afterEach(async () => {
+  if (httpServer) await new Promise<void>((r) => httpServer!.close(() => r()));
+  httpServer = undefined;
+  completeOAuth.mockClear();
+  completeOAuth.mockImplementation(async () => {});
+  vi.restoreAllMocks();
+});
+
+describe('isSafeReturnPath', () => {
+  it.each([
+    ['/secrets', true],
+    ['/skills-and-tools/tools/weather', true],
+    ['/', true],
+    ['/a?b=c&d=e', true], // a query is fine — it stays on our origin
+    ['/' + 'a'.repeat(511), true], // exactly 512 chars
+  ])('accepts %j', (value, expected) => {
+    expect(isSafeReturnPath(value)).toBe(expected);
+  });
+
+  it.each([
+    ['//evil.com', 'protocol-relative — leaves our origin'],
+    ['https://evil.com', 'absolute URL'],
+    ['http://evil.com', 'absolute URL'],
+    ['/\\evil.com', 'backslash folds to a slash in WHATWG http(s)'],
+    ['\\\\evil.com', 'backslash, no leading slash'],
+    ['/ok#fragment', 'would swallow the #authorized fragment'],
+    ['/ok\r\nSet-Cookie: a=b', 'response splitting'],
+    ['/ok\nX: y', 'response splitting'],
+    ['secrets', 'relative — no leading slash'],
+    ['', 'empty'],
+    ['/' + 'a'.repeat(512), '513 chars — over the state budget'],
+  ])('rejects %j (%s)', (value) => {
+    expect(isSafeReturnPath(value)).toBe(false);
+  });
+
+  it.each([[undefined], [null], [42], [{}], [['/ok']], [true]])('rejects the non-string %j', (value) => {
+    expect(isSafeReturnPath(value)).toBe(false);
+  });
+});
+
+describe('POST …/oauth/start — what gets signed into the state', () => {
+  it('signs a valid returnTo verbatim as `r`', async () => {
+    const state = await startAndReadState(await baseUrl(), { returnTo: RETURN_TO });
+    expect(state.r).toBe(RETURN_TO);
+    expect(state.u).toBe(`id-${USER}`);
+    expect(state.i).toBe('secret-1');
+  });
+
+  it('falls back to the legacy `connect` marker with NO body — byte-identical to the old behavior', async () => {
+    const state = await startAndReadState(await baseUrl());
+    expect(state.r).toBe('connect');
+  });
+
+  it('falls back to `connect` for an empty body and an absent returnTo', async () => {
+    const base = await baseUrl();
+    expect((await startAndReadState(base, {})).r).toBe('connect');
+    expect((await startAndReadState(base, { returnTo: undefined })).r).toBe('connect');
+  });
+
+  it.each([
+    ['//evil.com'],
+    ['https://evil.com'],
+    ['/ok#fragment'],
+    ['/\\evil.com'],
+    ['/' + 'a'.repeat(512)],
+    ['/ok\r\nSet-Cookie: a=b'],
+    ['not-a-path'],
+    [42],
+    [{ nested: true }],
+  ])('refuses %j and falls back to `connect`', async (returnTo) => {
+    const state = await startAndReadState(await baseUrl(), { returnTo });
+    expect(state.r).toBe('connect');
+  });
+});
+
+describe('GET /api/secrets/oauth/callback — where the browser lands', () => {
+  it('returns to a signed same-origin path', async () => {
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: RETURN_TO });
+    expect(await callback(base, state)).toBe(`${FRONTEND}${RETURN_TO}#authorized=secret-1`);
+  });
+
+  it('still lands a legacy `connect` state on /connect', async () => {
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: 'connect' });
+    expect(await callback(base, state)).toBe(`${FRONTEND}/connect#authorized=secret-1`);
+  });
+
+  it('lands a state with no `r` on /secrets (the standalone Secrets flow)', async () => {
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce' });
+    expect(await callback(base, state)).toBe(`${FRONTEND}/secrets#authorized=secret-1`);
+  });
+
+  it.each([['//evil.com'], ['https://evil.com'], ['/ok#frag'], ['/\\evil.com'], ['/ok\r\nX: y']])(
+    'refuses an unsafe `r` (%j) at CALLBACK time and falls back to /secrets',
+    async (unsafe) => {
+      // Defense in depth: this `r` is correctly signed — it could only exist if
+      // the signing key leaked or the start-side validation regressed. The
+      // callback re-checks anyway, because it is the line that builds the
+      // Location header.
+      const base = await baseUrl();
+      const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: unsafe });
+      expect(await callback(base, state)).toBe(`${FRONTEND}/secrets#authorized=secret-1`);
+    },
+  );
+
+  it('puts the error fragment on the RESOLVED destination when the exchange fails', async () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    completeOAuth.mockImplementation(async () => {
+      throw new Error('token endpoint said no');
+    });
+    const base = await baseUrl();
+    const state = signState({ u: 'u1', i: 'secret-1', n: 'nonce', r: RETURN_TO });
+    const location = await callback(base, state);
+    expect(location.startsWith(`${FRONTEND}${RETURN_TO}#error=`)).toBe(true);
+    // The user-facing message is generic — provider detail stays in the log.
+    expect(decodeURIComponent(location.split('#error=')[1])).toBe(
+      'Authorization failed. Check the provider configuration and try again.',
+    );
+  });
+
+  it('lands PRE-verification errors on /secrets, unchanged', async () => {
+    const base = await baseUrl();
+    // A tampered state can't be trusted for `r`, so its destination is the
+    // fallback — this is the behavior `returnTo` must not have altered.
+    const res = await fetch(`${base}/api/secrets/oauth/callback?code=abc&state=garbage.sig`, {
+      redirect: 'manual',
+    });
+    expect(res.headers.get('location')).toBe(
+      `${FRONTEND}/secrets#error=${encodeURIComponent('OAuth state mismatch.')}`,
+    );
+    const noCode = await fetch(`${base}/api/secrets/oauth/callback`, { redirect: 'manual' });
+    expect(noCode.headers.get('location')).toBe(
+      `${FRONTEND}/secrets#error=${encodeURIComponent('Invalid OAuth callback.')}`,
+    );
+  });
+
+  it('round-trips a returnTo end to end: start signs it, callback honors it', async () => {
+    const base = await baseUrl();
+    const res = await fetch(`${base}/api/secrets/tools/weather/vars/SIGNIN/oauth/start`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ returnTo: RETURN_TO }),
+    });
+    const { url } = (await res.json()) as { url: string };
+    const state = new URL(url).searchParams.get('state')!;
+    expect(await callback(base, state)).toBe(`${FRONTEND}${RETURN_TO}#authorized=secret-1`);
+  });
+});