Static Verification: Catch Ungated Actions with alfiz-verify

npm install --save-dev @alfiz/verify

{
  "scripts": {
    "verify:permissions": "alfiz-verify"
  }
}

node --experimental-strip-types -e \
  'import("./src/alfiz.ts").then(m => console.log(JSON.stringify(m.catalog.toDocument())))' \
  > alfiz-catalog.json

await alfiz.can({ userId }, "docs.files.reed"); // TS error: not assignable to KeyOf<typeof catalog>
await alfiz.can({ userId }, "docs.files.read"); // OK

⚠ [unreferenced-leaf] <catalog> — "docs.files.read_history" is declared but referenced by no gate or nav item — dead permission, or missing enforcement?
✖ [ungated-action] app/actions/export.ts:14 — exported server action "exportDocument" contains no gate — every action gates on a concrete permission before doing work

✖ [visibility-as-gate] app/api/drive/route.ts:12 — canAny() is a visibility affordance, never a gate — server actions and route handlers gate on a concrete permission (can/require*)

✖ [missing-condition] app/actions/claims.ts:12 — "exp.claims.approve_claim" is declared `requiresCondition: true` — the gate must pass `{ condition: () => … }` evaluating the resource predicate; without it the check throws MissingConditionError at runtime

✖ [catalog] docs.files — below the naming floor: every tab defines at least one read permission (`read` or `read_<thing>`)
✖ [catalog] docs.files.sharing.read — is 4 levels deep; this catalog's convention is 3
⚠ [catalog] docs.files.Publish — actions are named `<verb>_<noun>` in snake_case (destructive actions may stand alone, e.g. `delete`)

conventions: { depth: 2 }      // an integration catalog: zoom.host
conventions: { depth: 4 }      // a deeper feature tree
conventions: { depth: "any" }  // no depth check at all

{
  "catalog": "alfiz-catalog.json",
  "include": ["src", "app"],
  "exclude": ["node_modules", "dist"],
  "gateNames": ["assertCanEditFile", "gateDestructiveAction"],
  "visibilityNames": ["showIfAny"],
  "serverFilePatterns": ["app/actions/"],
  "forbidClientIdentifiers": ["ALFIZ_SERVICE_KEYS"]
}

// lib/auth.ts — project wrapper
export async function gateDestructiveAction(userId: string, key: KeyOf<typeof catalog>, scope: ScopeId) {
  return alfiz.can.fresh({ userId }, key, scope);
}

export async function assertCanEditFile(userId: string, folderId: string) {
  await alfiz.require({ userId }, "docs.files.update_file", `docs.folder:${folderId}`);
}

{
  "gateNames": ["gateDestructiveAction", "assertCanEditFile"]
}

// alfiz-verify-ignore-file system trust domain, authenticates by deploy key
"use server";

// This file verifies inbound webhook signatures — there is no catalog-keyed
// permission to gate on, and adding a fake one would be misleading.
export async function handleWebhook(req: Request) { ... }

○ [ignored] app/webhooks/stripe.ts — system trust domain, authenticates by deploy key

// alfiz-verify-ignore-next-line implicit-import legacy zoom bridge, removed in Q3
await client.can(user, legacyKey);

await client.can(user, k); // alfiz-verify-ignore-line implicit-import same bridge

<symbol> [<rule>] <file>:<line> — <message>

⚠ [unreferenced-leaf] <catalog> — "docs.files.read_history" is declared but referenced by no gate or nav item — dead permission, or missing enforcement?
✖ [ungated-action] app/actions/export.ts:14 — exported server action "exportDocument" contains no gate — every action gates on a concrete permission before doing work
✖ [visibility-as-gate] app/api/drive/route.ts:12 — canAny() is a visibility affordance, never a gate — server actions and route handlers gate on a concrete permission (can/require*)
alfiz-verify: 47 file(s), 1 ignored, 2 error(s), 1 warning(s)

# .github/workflows/ci.yml
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - run: npm ci

      - name: Build
        run: npx tsc -b

      - name: Emit catalog
        run: |
          node --experimental-strip-types -e \
            'import("./src/alfiz.ts").then(m => console.log(JSON.stringify(m.catalog.toDocument())))' \
            > alfiz-catalog.json

      - name: Verify permissions
        run: npx alfiz-verify