bridgebench 3.1.0-alpha.1 → 3.1.0-alpha.2

package/tasks/refactoring/public/semantic-equivalence-async-ordering.yaml

@@ -0,0 +1,157 @@
+id: semantic-equivalence-async-ordering
+version: 1.0.0
+category: refactoring
+cluster: semantic-equivalence
+difficulty: expert
+title: Are these six async refactors behavior-preserving under Promise ordering and error semantics?
+summary: Six async functions each get a rewrite that changes how promises are sequenced. Some are equivalent; others diverge on ordering of observable side effects, how many metered calls run on the error path, whether a non-idempotent write always fires, or whether rejections still propagate. Using the cited Promise semantics and the declared side effects, classify each rewrite as behavior-preserving or changes-behavior.
+prompt: |
+  A refactor PR rewrites six async functions (originals A1..A6) into forms that sequence their
+  promises differently (proposed B1..B6). Judge each rewrite for FULL observable equivalence across
+  BOTH the success path and the error path, accounting for the declared side effects.
+
+  Answer each deliverable using ONLY the supplied artifacts (async-spec, side-effects, originals,
+  proposed). Cite the artifact id(s) for every claim; ground each divergence in async-spec and in
+  the observable side effect declared in side-effects.
+
+  For each rewrite below, classify it as exactly one of:
+    - behavior-preserving  (same observable behavior as the original on every path: same results,
+                            same ordering of observable side effects, same set of calls actually
+                            made, same rejection/throw behavior)
+    - changes-behavior     (differs on some path; name the single divergence and a condition that
+                            witnesses it)
+
+  1. Classify B1 (rewrite of A1).
+  2. Classify B2 (rewrite of A2).
+  3. Classify B3 (rewrite of A3).
+  4. Classify B4 (rewrite of A4).
+  5. Classify B5 (rewrite of A5).
+  6. Classify B6 (rewrite of A6).
+
+  Exactly one classification is defensible per deliverable; it is fully determined by the async
+  semantics and the declared side effects.
+artifacts:
+  - id: async-spec
+    type: spec
+    label: Promise / async semantics (authoritative for this task)
+    content: |
+      Semantics you must apply:
+
+      A. `await x` suspends the async function until x settles. Statements after it run ONLY after x
+         resolves. If x rejects, execution stops there as if `throw` were reached and the function's
+         returned promise rejects; later statements do not run.
+
+      B. Sequential awaits `await f(); await g();` invoke g() only AFTER f() has resolved. If f()
+         rejects, g() is never invoked.
+
+      C. `Promise.all([e1, e2, ...])`: the array is built EAGERLY, so every expression e1, e2, ...
+         is invoked immediately (all underlying operations start concurrently, before any awaiting).
+         It resolves to results in INPUT ORDER once all resolve. It rejects as soon as ANY input
+         rejects, with that first rejection; the other already-started promises keep running (their
+         side effects still occur) and their results are discarded.
+
+      D. `Promise.allSettled([...])` NEVER rejects; it resolves once all inputs settle, to an array
+         of { status, value | reason }.
+
+      E. `arr.map(fn)` invokes fn for every element eagerly during the map; for an async fn, all
+         calls start concurrently.
+
+      F. Operand order of `+` is left-to-right: in `(await f()) + (await g())`, f() is invoked and
+         its await fully resolves BEFORE g() is invoked — identical ordering to two sequential
+         `const` awaits.
+
+      G. `p.then(cb)` returns a promise that resolves to cb's return value, or rejects if p rejects
+         or cb throws. `const u = await p; return cb(u);` has the SAME settle behavior (same
+         resolution value, same rejection).
+  - id: side-effects
+    type: note
+    label: observable side effects of the helper calls (authoritative)
+    content: |
+      What is observable about each helper (this determines what "same behavior" requires):
+
+      - log(x): appends x to an append-only audit stream. The server assigns each entry a sequence
+        number BY ARRIVAL ORDER, so the order in which log() calls arrive is OBSERVABLE. log()
+        returns nothing meaningful.
+      - fetchOne(id): a METERED network GET. Each invocation consumes one unit of a rate quota and
+        is recorded, so the NUMBER of fetchOne() invocations is OBSERVABLE. It may reject.
+      - exists(id): a read with no observable side effect. create(id): INSERTS a row; it is
+        non-idempotent — a second create for an id that already exists is an observable duplicate/
+        error. Whether create() runs is OBSERVABLE.
+      - save(item): a write that may reject. Whether the enclosing function THROWS to its caller is
+        OBSERVABLE.
+      - getBase(id), getBonus(id), getUser(id): pure reads; no ordering-sensitive side effects.
+  - id: originals
+    type: code
+    label: original async functions (A1..A6)
+    content: |
+      // A1 — write two audit entries in order
+      async function audit(a: string, b: string): Promise<void> {
+        await log(a);
+        await log(b);
+      }
+
+      // A2 — sum of two fetched amounts
+      async function total(id: string): Promise<number> {
+        return (await getBase(id)) + (await getBonus(id));
+      }
+
+      // A3 — load every record; stop at the first failure
+      async function loadAll(ids: string[]): Promise<Rec[]> {
+        const out: Rec[] = [];
+        for (const id of ids) out.push(await fetchOne(id));
+        return out;
+      }
+
+      // A4 — fetch a user's name
+      function fetchName(id: string): Promise<string> {
+        return getUser(id).then((u) => u.name);
+      }
+
+      // A5 — create the record only if it does not already exist
+      async function ensure(id: string): Promise<void> {
+        if (await exists(id)) return;
+        await create(id);
+      }
+
+      // A6 — persist every item; fail if any save fails
+      async function saveAll(items: Item[]): Promise<void> {
+        await Promise.all(items.map(save));
+      }
+  - id: proposed
+    type: code
+    label: proposed async rewrites (B1..B6)
+    content: |
+      // B1 — rewrite of A1
+      async function audit(a: string, b: string): Promise<void> {
+        await Promise.all([log(a), log(b)]);
+      }
+
+      // B2 — rewrite of A2
+      async function total(id: string): Promise<number> {
+        const base = await getBase(id);
+        const bonus = await getBonus(id);
+        return base + bonus;
+      }
+
+      // B3 — rewrite of A3
+      async function loadAll(ids: string[]): Promise<Rec[]> {
+        return Promise.all(ids.map((id) => fetchOne(id)));
+      }
+
+      // B4 — rewrite of A4
+      async function fetchName(id: string): Promise<string> {
+        const u = await getUser(id);
+        return u.name;
+      }
+
+      // B5 — rewrite of A5
+      async function ensure(id: string): Promise<void> {
+        const [present] = await Promise.all([exists(id), create(id)]);
+        if (present) return;
+      }
+
+      // B6 — rewrite of A6
+      async function saveAll(items: Item[]): Promise<void> {
+        await Promise.allSettled(items.map(save));
+      }
+tags: [semantic-equivalence, refactoring, async, promises, ordering]

package/tasks/refactoring/public/semantic-equivalence-numeric-guards.yaml

@@ -0,0 +1,115 @@
+id: semantic-equivalence-numeric-guards
+version: 1.1.0
+category: refactoring
+cluster: semantic-equivalence
+difficulty: expert
+title: Are these six JavaScript simplifications behavior-preserving across all inputs?
+summary: Six small pure functions each have a proposed one-line simplification. Some are equivalent for every input; others break on a specific edge case (falsy zero vs nullish, 32-bit shift truncation, IEEE-754 rounding and overflow, floor vs truncation of negatives). Using the cited language semantics, classify each rewrite as behavior-preserving or changes-behavior and give a witness input for every change.
+prompt: |
+  A "simplify" PR rewrites six pure JavaScript functions (originals O1..O6) into shorter forms
+  (proposed P1..P6). Judge each rewrite for FULL semantic equivalence: it is behavior-preserving
+  only if it returns the same value as the original for EVERY input in the parameter's type, with
+  the same numeric result and sign. Do not assume a narrower input domain than the type allows.
+
+  Answer each deliverable using ONLY the supplied artifacts (language-spec, originals, proposed).
+  Cite the artifact id(s) for every claim; ground each edge case in the language-spec.
+
+  For each rewrite below, classify it as exactly one of:
+    - behavior-preserving  (equal to the original for every input)
+    - changes-behavior     (differs on some input; give a concrete witness input and the resulting
+                            two values, and cite the language-spec rule that explains the divergence)
+
+  1. Classify P1 (rewrite of O1).
+  2. Classify P2 (rewrite of O2).
+  3. Classify P3 (rewrite of O3).
+  4. Classify P4 (rewrite of O4).
+  5. Classify P5 (rewrite of O5).
+  6. Classify P6 (rewrite of O6).
+
+  Exactly one classification is defensible per deliverable; it is fully determined by the language
+  semantics in language-spec applied to the two forms.
+artifacts:
+  - id: language-spec
+    type: spec
+    label: relevant JavaScript evaluation semantics (authoritative for this task)
+    content: |
+      Semantics you must apply (these govern every deliverable):
+
+      A. Logical OR `a || b`  -> returns `a` if `a` is TRUTHY, otherwise returns `b`.
+         The FALSY values are exactly: false, 0, -0, 0n, "", null, undefined, NaN.
+
+      B. Nullish coalescing `a ?? b` -> returns `a` UNLESS `a` is null or undefined, in which case
+         it returns `b`. 0, -0, "", NaN, and false are NOT nullish, so `a ?? b` returns them.
+
+      C. Logical AND `a && b` -> returns `a` if `a` is falsy, otherwise returns `b`.
+         Logical NOT `!x` -> a boolean, true iff `x` is falsy. Consequently the De Morgan identity
+         `!(a && b)` === `!a || !b` holds as booleans for all `a`, `b`.
+
+      D. Left shift `x << k` -> `x` is first converted with ToInt32: any fractional part is
+         truncated toward zero and the value is reduced modulo 2^32 into the signed range
+         [-2147483648, 2147483647]; THEN it is shifted. The result is a 32-bit signed integer.
+
+      E. Bitwise OR with zero `x | 0` -> applies ToInt32 to `x` (truncates the fraction toward zero,
+         reduces modulo 2^32 into the signed 32-bit range). For non-integers it truncates TOWARD
+         ZERO; for |x| >= 2^31 it wraps.
+
+      F. `Math.floor(x)` -> the greatest integer <= x, i.e. it rounds toward -Infinity. For negative
+         non-integers this differs from truncation toward zero (e.g. floor(-1.5) = -2, trunc = -1).
+
+      G. Numbers are IEEE-754 doubles. `*` and `/` round each intermediate result to the nearest
+         representable double; there is no integer wraparound, but a magnitude above
+         Number.MAX_VALUE becomes Infinity. Because each operation rounds independently,
+         `a/2 + b/2` and `(a + b)/2` are NOT guaranteed to be the same double, and `a + b` can be
+         Infinity while `a/2 + b/2` is finite.
+
+      H. Operand evaluation order for `+`, `&&`, `||`, `??` is left-to-right; `&&`, `||`, and `??`
+         short-circuit (do not evaluate the right operand) when the left already determines the
+         result.
+  - id: originals
+    type: code
+    label: original functions (O1..O6), each pure
+    content: |
+      // Each parameter may be ANY value of its annotated type; assume no narrower domain.
+
+      // O1 — choose the configured port, else default 8080
+      function port(p: number): number { return p || 8080; }
+
+      // O2 — should we skip when NOT both a and b hold
+      function shouldSkip(a: unknown, b: unknown): boolean { return !(a && b); }
+
+      // O3 — double an integer count
+      function double(n: number): number { return n * 2; }
+
+      // O4 — first of two values that is truthy, else the second
+      function firstTruthy(a: unknown, b: unknown): unknown {
+        if (a) return a;
+        return b;
+      }
+
+      // O5 — midpoint of two finite numbers
+      function avg(a: number, b: number): number { return a / 2 + b / 2; }
+
+      // O6 — integer half, rounding down
+      function half(n: number): number { return Math.floor(n / 2); }
+  - id: proposed
+    type: code
+    label: proposed simplifications (P1..P6)
+    content: |
+      // P1 — rewrite of O1
+      function port(p: number): number { return p ?? 8080; }
+
+      // P2 — rewrite of O2
+      function shouldSkip(a: unknown, b: unknown): boolean { return !a || !b; }
+
+      // P3 — rewrite of O3
+      function double(n: number): number { return n << 1; }
+
+      // P4 — rewrite of O4
+      function firstTruthy(a: unknown, b: unknown): unknown { return a || b; }
+
+      // P5 — rewrite of O5
+      function avg(a: number, b: number): number { return (a + b) / 2; }
+
+      // P6 — rewrite of O6
+      function half(n: number): number { return (n / 2) | 0; }
+tags: [semantic-equivalence, refactoring, javascript, floating-point, edge-cases]

package/tasks/security/public/authz-guard-chain-exposure.yaml

@@ -0,0 +1,224 @@
+id: authz-guard-chain-exposure
+version: 1.1.0
+category: security
+cluster: authz-boundary
+difficulty: expert
+title: Cobalt API Global Guard Chain — Route Exposure Analysis
+summary: >-
+  The Cobalt service protects routes with a global guard chain (authentication →
+  role → tier → CSRF) plus per-controller @UseGuards and route decorators.
+  Several admin-looking routes appear risky; exactly one is a genuine
+  unauthenticated exposure. Classify five named routes against declared intent,
+  identify the single real exposure, and state the fix — using only the artifacts.
+prompt: |
+  You are reviewing authorization on the "Cobalt" API. Guards are registered
+  globally and also, redundantly, per controller; individual routes carry
+  decorators like @Public(), @Roles(), @RequireTier(), and @FeatureEnabled().
+  You are given seven artifacts: admin-controller, billing-controller,
+  public-controller, guard-registration, decorator-reference, feature-flags, and
+  exposure-note.
+
+  Answer each item using ONLY the supplied artifacts. Cite the artifact id(s) you
+  rely on for every claim. If something is not defined/reachable/exploitable in
+  the artifacts, say so explicitly. Do NOT write exploit code, requests, or
+  bypass strings — this is an analysis-only task.
+
+  For items 1–5, state (a) who can successfully call the route (an unauthenticated
+  caller, any authenticated user, an authenticated user of a given tier, an
+  authenticated ADMIN, or no one in production), and (b) whether that matches the
+  declared intent. Justify every answer by citing the specific decorators on the
+  route, the global guard chain and its ORDER, and the relevant declarations.
+
+  1. DELETE /admin/workspaces/:id  (AdminController.deleteWorkspace)
+  2. POST  /admin/keys/rotate      (AdminController.rotateSigningKeys)
+  3. GET   /billing/invoices       (BillingController.getInvoices)
+  4. POST  /admin/audit/purge      (AdminController.purgeAuditLog)
+  5. GET   /public/health          (PublicController.health)
+
+  6. Exactly one route in this service is an UNINTENDED exposure — reachable by a
+     caller who should not reach it. Name that single route and state the
+     destructive action it lets that caller trigger. Ground the claim in the
+     decorators, the guard chain, and the intended-public declaration.
+
+  7. State the one-line fix that closes the exposure from item 6, and explain why
+     it restores the intended protection (cite the guard chain / decorator
+     semantics).
+artifacts:
+  - id: admin-controller
+    type: code
+    label: cobalt-api/src/admin/admin.controller.ts
+    content: |
+      // The @UseGuards + @Roles here are class-level; the authentication and role
+      // guards are ALSO registered globally (see guard-registration), so these are
+      // defense-in-depth. This file lists EVERY route on the /admin controller;
+      // there are no other admin routes.
+
+      @Controller('admin')
+      @UseGuards(JwtAuthGuard, RoleGuard)   // redundant with the global chain
+      @Roles(Role.ADMIN)                    // class default: /admin is admin-only...
+      export class AdminController {
+        // Permanently and irreversibly deletes a workspace together with ALL of
+        // its projects, members, invitations, and billing history.
+        @Delete('workspaces/:id')
+        @Public()
+        deleteWorkspace(@Param('id') id: string) {
+          return this.admin.deleteWorkspace(id);
+        }
+
+        // Rotates the JWT signing keys for the entire tenant.
+        @Post('keys/rotate')
+        rotateSigningKeys() {
+          return this.admin.rotateSigningKeys();
+        }
+
+        // Hard-deletes the append-only audit log. Gated behind a feature flag.
+        @Post('audit/purge')
+        @FeatureEnabled('beta-shredder')
+        purgeAuditLog() {
+          return this.admin.purgeAuditLog();
+        }
+      }
+  - id: billing-controller
+    type: code
+    label: cobalt-api/src/billing/billing.controller.ts
+    content: |
+      // NOTE: this controller declares NO class-level @UseGuards of its own.
+      // This file lists every route on the /billing controller.
+
+      @Controller('billing')
+      export class BillingController {
+        // Lists the caller's own invoices. Requires an active PRO (or higher) tier.
+        @Get('invoices')
+        @RequireTier('PRO')
+        getInvoices(@GetUser('id') userId: string) {
+          return this.billing.listInvoices(userId);
+        }
+
+        // Opens the billing provider's portal session for the caller.
+        @Post('portal-session')
+        @RequireTier('BASIC')
+        createPortalSession(@GetUser('id') userId: string) {
+          return this.billing.createPortalSession(userId);
+        }
+      }
+  - id: public-controller
+    type: code
+    label: cobalt-api/src/public/public.controller.ts
+    content: |
+      // This file lists every route on the /public controller.
+
+      @Controller('public')
+      export class PublicController {
+        // Liveness probe for the load balancer. Intentionally unauthenticated.
+        @Get('health')
+        @Public()
+        health() {
+          return { status: 'ok' };
+        }
+
+        // Pricing table rendered by the unauthenticated marketing site.
+        @Get('pricing')
+        @Public()
+        pricing() {
+          return this.catalog.publicPricing();
+        }
+      }
+  - id: guard-registration
+    type: code
+    label: cobalt-api/src/app.module.ts (global guard registration — complete)
+    content: |
+      // The COMPLETE set of globally-registered guards. APP_GUARD guards run for
+      // EVERY route in the application — including controllers that declare no
+      // @UseGuards of their own — in the order they are registered below. There
+      // are no other global guards.
+
+      providers: [
+        { provide: APP_GUARD, useClass: JwtAuthGuard }, // 1. authentication
+        { provide: APP_GUARD, useClass: RoleGuard },    // 2. role check (needs the
+                                                        //    principal from step 1)
+        { provide: APP_GUARD, useClass: TierGuard },    // 3. subscription tier
+        { provide: APP_GUARD, useClass: CsrfGuard },    // 4. CSRF (mutating verbs)
+      ];
+
+      // Ordering guarantee: Nest executes APP_GUARD providers in registration
+      // order. Authentication (1) therefore ALWAYS runs before the role check (2),
+      // which always runs before the tier check (3). A caller with no valid token
+      // is rejected at step 1 and never reaches steps 2–4 — UNLESS the route opts
+      // out of authentication via @Public() (see decorator-reference).
+  - id: decorator-reference
+    type: spec
+    label: Cobalt authorization decorator reference (authoritative)
+    content: |
+      Authoritative meaning of every authorization decorator in Cobalt. This is
+      the complete list; no other authorization decorators exist in the codebase.
+
+      @UseGuards(...guards)
+        Attaches controller/route-scoped guards. In Cobalt these DUPLICATE guards
+        that are also registered globally (see guard-registration); they are
+        defense-in-depth and add no protection beyond the global chain. A
+        controller WITHOUT @UseGuards is still fully covered by the global chain.
+
+      @Public()
+        Marks a route (or controller) as NOT requiring authentication. When
+        present, the authentication guard (step 1) short-circuits to ALLOW. Because
+        no authenticated principal is then established, the role guard (step 2)
+        ALSO allows the request — it has no principal to evaluate and treats the
+        route as public. Net effect: a @Public() route is reachable by ANY caller,
+        with no token and no role, REGARDLESS of any @Roles present on the same
+        route or its controller.
+
+      @Roles(role)
+        Requires the authenticated principal to hold `role`. Enforced by the role
+        guard (step 2), which runs AFTER authentication (step 1). It therefore can
+        never be reached by an unauthenticated caller UNLESS the route is @Public().
+        A class-level @Roles applies to every route on the controller that is not
+        @Public().
+
+      @RequireTier(tier)
+        Requires the authenticated principal's subscription tier to be `tier` or
+        higher (FREE < BASIC < PRO < ULTRA). Enforced by the tier guard (step 3).
+        Implies authentication: an unauthenticated caller is rejected at step 1
+        before the tier guard runs.
+
+      @FeatureEnabled(flag)
+        The route responds 404 (as though it did not exist) whenever `flag` is not
+        enabled in the running environment (see feature-flags). A disabled flag
+        makes the route unreachable in that environment.
+
+      @SkipCsrf()
+        Exempts a route from the CSRF guard (step 4) ONLY. It has NO effect on the
+        authentication, role, or tier checks.
+
+      CsrfGuard is NOT an authentication or authorization control. It exists only
+      to reject FORGED state-changing requests that ride ambient session
+      credentials — e.g. a browser that auto-attaches session cookies — when a
+      valid CSRF token is absent. A direct, credential-less API call carries no
+      ambient session to forge against, so CsrfGuard does NOT block it, on ANY HTTP
+      verb (including DELETE). CsrfGuard can therefore never turn a @Public() route
+      back into a protected one: a route left reachable by @Public() is reachable by
+      an unauthenticated direct caller regardless of verb.
+  - id: feature-flags
+    type: config
+    label: cobalt feature flags (resolved values, production)
+    content: |
+      # Resolved feature-flag values. This file is the COMPLETE flag set; any flag
+      # not listed here is treated as disabled in every environment.
+      flags:
+        beta-shredder:   { prod: false, staging: true }   # audit-log purge (admin)
+        new-invoice-pdf: { prod: true,  staging: true }
+        workspace-export:{ prod: true,  staging: true }
+  - id: exposure-note
+    type: note
+    label: Cobalt intended-public route inventory (authoritative)
+    content: |
+      Intended-public route inventory. The routes below are the ONLY routes in the
+      service intended to be reachable WITHOUT authentication. Every other route
+      must require a valid token.
+
+        - GET /public/health    (load-balancer liveness probe)
+        - GET /public/pricing   (marketing pricing table)
+
+      Any route that carries @Public() but is NOT in this list is a
+      misconfiguration: per the decorator-reference, @Public() disables BOTH the
+      authentication and the role checks for that route.
+tags: [authz, guards, nestjs, access-control, authz-boundary, security]