finitemonkey 0.1.0-next.2 → 0.1.0-next.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "finitemonkey",
-  "version": "0.1.0-next.2",
+  "version": "0.1.0-next.21",
   "description": "Claude Code hooks that stop a coding agent from saying done before the tests pass: a machine-checked definition of done, plus guardrails for secrets, git safety and production. Pre-release.",
   "type": "module",
   "license": "Apache-2.0",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "runbooks",
     "LICENSE",
     "NOTICE",
     "README.md"
@@ -55,13 +56,24 @@
     "i18n:check": "node dist/finitemonkey.mjs i18n check --dir src/i18n",
     "bench:startup": "node scripts/bench-startup.mjs",
     "smoke:install": "node scripts/smoke-install.mjs",
-    "check": "npm run typecheck && npm run lint && npm run format:check && npm run check:dist && npm test && npm run i18n:check && npm pack --dry-run && npm run llms:check",
+    "check": "npm run typecheck && npm run lint && npm run format:check && npm run check:dist && npm test && npm run i18n:check && npm run plugin:validate && npm pack --dry-run && npm run llms:check && npm run schema:check && npm run docs:check && npm run runbooks:check",
     "prepublishOnly": "npm run typecheck && npm run check:dist && npm test",
     "prepare": "husky",
     "gif": "tsc -p assets/scripts && node --experimental-strip-types assets/scripts/render.ts",
     "social": "tsc -p assets/scripts && node --experimental-strip-types assets/scripts/social.ts",
     "llms": "tsx scripts/build-llms.ts",
-    "llms:check": "tsc -p scripts && tsx scripts/build-llms.ts --check"
+    "llms:check": "tsc -p scripts && tsx scripts/build-llms.ts --check",
+    "llms:stamp": "tsx scripts/build-llms.ts --stamp",
+    "schema": "tsx scripts/build-schemas.ts",
+    "schema:check": "tsx scripts/build-schemas.ts --check",
+    "budgets": "tsx scripts/budgets.ts",
+    "docs": "tsx scripts/build-docs.ts",
+    "docs:check": "tsc -p scripts && tsx scripts/build-docs.ts --check",
+    "runbooks:check": "tsx scripts/check-runbooks.ts",
+    "e2e:claude": "node --import tsx --test --test-concurrency=1 test/e2e/claude-stop.e2e.ts",
+    "plugin:sync": "node scripts/plugin-sync.mjs",
+    "plugin:validate": "node scripts/plugin-validate.mjs",
+    "version": "node scripts/plugin-sync.mjs"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.4",
@@ -76,6 +88,7 @@
     "eslint": "^10.13.0",
     "eslint-plugin-simple-import-sort": "^14.0.0",
     "husky": "^9.1.7",
+    "playwright-core": "^1.64.1",
     "prettier": "^3.9.10",
     "semantic-release": "^25.0.9",
     "tsx": "^4.23.15",

package/runbooks/anthropic.md

@@ -0,0 +1,31 @@
+# Anthropic API keys
+
+Applies to rule `anthropic-api-key`.
+
+## 1. Revoke
+
+In the Claude Console, open **Settings** > **API keys** and disable or delete the key. With an admin key, `POST /v1/organizations/api_keys/{api_key_id}` with `{"status": "inactive"}` does the same.
+
+## 2. Issue the new credential
+
+Create the new key in a workspace that holds only this application, with spend limits set on that workspace. Do not reuse one key across environments.
+
+## 3. Replace it in every consumer
+
+Update the secret store, CI secrets and every service that reads `ANTHROPIC_API_KEY`.
+
+## 4. Check for misuse in the exposure window
+
+Review usage and cost for the workspace in the window. Requests or spend you cannot explain mean the key was used by someone else.
+
+## 5. Delete the old credential after observation
+
+After a few days with no errors from consumers, archive or delete the disabled key.
+
+## 6. Notification duties
+
+Prompts and files sent with the key may hold personal data. If the key could read stored files or batches, assess notice duties.
+
+## Sources
+
+- https://platform.claude.com/docs/en/api/admin-api/apikeys/update-api-key (accessed 2026-10-26)

package/runbooks/asaas.md

@@ -0,0 +1,31 @@
+# Asaas API keys
+
+Applies to rule `asaas-api-key`.
+
+## 1. Revoke
+
+As an account administrator, open **Integrações** in the web interface and delete the exposed key. A deleted key cannot be restored. A parent account can also revoke a subaccount key through the API.
+
+## 2. Issue the new credential
+
+Create the new key in the same area. Use a separate key per subaccount and per environment, and never put a production key in a sandbox configuration.
+
+## 3. Replace it in every consumer
+
+Update the backend secret store, CI secrets and every worker that calls the API.
+
+## 4. Check for misuse in the exposure window
+
+Review charges, transfers, PIX keys, bank account changes and webhook settings for the window, in the account and in every subaccount the key could reach.
+
+## 5. Delete the old credential after observation
+
+If you created a temporary key during the switch, delete it after a few days without errors.
+
+## 6. Notification duties
+
+Asaas keys reach customer names, tax ids and payment data. If they were read, assess notice duties under the LGPD toward the ANPD and the people affected.
+
+## Sources
+
+- https://docs.asaas.com/docs/chaves-de-api (accessed 2026-10-26)

package/runbooks/aws.md

@@ -0,0 +1,32 @@
+# AWS access keys
+
+Applies to rules `aws-access-token` and `aws-secret-access-key`.
+
+## 1. Revoke
+
+In the IAM console, open the user, then **Security credentials** > **Access keys**, and set the exposed key to **Inactive** (`aws iam update-access-key --access-key-id <id> --status Inactive --user-name <user>`). Inactive keys stop signing requests at once and can still be turned back on if something critical breaks.
+
+## 2. Issue the new credential
+
+Prefer no long-lived key at all: an IAM role for EC2, ECS or Lambda, or OIDC federation for CI (GitHub Actions `aws-actions/configure-aws-credentials` with a role). If a key is unavoidable, create it on a user whose policy grants only what the consumer needs (`aws iam create-access-key --user-name <user>`).
+
+## 3. Replace it in every consumer
+
+Update the secret store, CI secrets, `.env` files outside git, and every host that had the old key. Restart the processes that read it at start.
+
+## 4. Check for misuse in the exposure window
+
+Run `aws iam get-access-key-last-used --access-key-id <id>` and search CloudTrail for the key id from the first exposure until it went inactive. Look for new IAM users, new keys, new regions, EC2 instances you did not start and S3 reads you do not recognize.
+
+## 5. Delete the old credential after observation
+
+After a few days with no errors from consumers and no use of the old id, delete it (`aws iam delete-access-key --access-key-id <id> --user-name <user>`).
+
+## 6. Notification duties
+
+If CloudTrail shows access to personal data, the data protection law that applies (LGPD, GDPR or a state law) may require notice to the regulator and to the people affected. Record what was reachable with the key and decide with whoever owns that duty.
+
+## Sources
+
+- https://docs.aws.amazon.com/IAM/latest/UserGuide/id-credentials-access-keys-update.html (accessed 2026-10-26)
+- https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html (accessed 2026-10-26)

package/runbooks/cloudflare.md

@@ -0,0 +1,31 @@
+# Cloudflare API tokens
+
+Applies to Cloudflare API tokens and global API keys found by the generic rules.
+
+## 1. Revoke
+
+Go to **My Profile** > **API Tokens**, open the menu next to the token and choose **Roll**. Rolling invalidates the old secret at once and keeps the same permissions. A global API key can be changed on the same page.
+
+## 2. Issue the new credential
+
+Prefer a scoped API token over the global API key: only the zones and permissions the consumer needs, with client IP filtering and a TTL when the consumer runs from known addresses.
+
+## 3. Replace it in every consumer
+
+Update CI secrets, Workers secrets, Terraform variables and any tool that calls the API.
+
+## 4. Check for misuse in the exposure window
+
+Read the account audit log for the window: DNS changes, new Workers or routes, page rules, firewall changes, new members and new tokens.
+
+## 5. Delete the old credential after observation
+
+Delete any extra token created during the change once consumers have run without errors for a few days.
+
+## 6. Notification duties
+
+DNS or Workers changes can redirect user traffic. If that happened, treat it as a breach of the affected service and assess notice duties.
+
+## Sources
+
+- https://developers.cloudflare.com/fundamentals/api/how-to/roll-token/ (accessed 2026-10-26)

package/runbooks/database.md

@@ -0,0 +1,32 @@
+# Database and Redis passwords
+
+Applies to rules `credential-in-url`, `password-assignment` and `secret-in-process-args` when the value is a database or Redis password.
+
+## 1. Revoke
+
+PostgreSQL: `ALTER ROLE <role> WITH PASSWORD NULL;` or `ALTER ROLE <role> NOLOGIN;` until the new password is in place. MySQL: `ALTER USER '<user>'@'<host>' ACCOUNT LOCK;`. Redis with ACLs: remove the password from the user (`ACL SETUSER <user> <<old-password>`), or with `requirepass` change it in the config and restart.
+
+## 2. Issue the new credential
+
+Generate a long random password (`ACL GENPASS` in Redis, `openssl rand -base64 32` elsewhere), or move to IAM database authentication or short-lived credentials from a secrets manager. Give each application its own role with only the grants it needs.
+
+## 3. Replace it in every consumer
+
+Update connection strings in the secret store, compose files (from a variable, never a literal argument), CI, migrations and backup jobs. Restart connection pools.
+
+## 4. Check for misuse in the exposure window
+
+Check the server log for logins from unknown addresses, `pg_stat_activity` or `SHOW PROCESSLIST` for unknown sessions, and look for new roles, changed grants, dropped tables or large reads. Check whether the port was reachable from the internet during the window.
+
+## 5. Delete the old credential after observation
+
+Remove temporary roles or extra Redis passwords added for the switch after the applications have run cleanly for a few days.
+
+## 6. Notification duties
+
+A database usually holds personal data. If anyone outside your team could have connected, treat it as a possible breach and assess notice duties toward the regulator and the people affected.
+
+## Sources
+
+- https://www.postgresql.org/docs/17/sql-alterrole.html (accessed 2026-10-26)
+- https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/ (accessed 2026-10-26)

package/runbooks/digitalocean.md

@@ -0,0 +1,31 @@
+# DigitalOcean API tokens
+
+Applies to DigitalOcean personal access tokens (`dop_v1_`) found by the generic rules.
+
+## 1. Revoke
+
+In the control panel, open **API** > **Tokens**, find the token and choose **Delete**, or **Regenerate** if consumers must keep the same name and scopes.
+
+## 2. Issue the new credential
+
+Create a token with custom scopes limited to the resources the consumer touches and an expiration date. Scopes cannot be edited later, so pick them now.
+
+## 3. Replace it in every consumer
+
+Update CI secrets, `doctl auth` contexts, Terraform variables and every host that used the old token.
+
+## 4. Check for misuse in the exposure window
+
+Review the account's security history and the resource list for the window: new Droplets, volumes, snapshots, firewall changes, new SSH keys and Spaces access keys you did not create.
+
+## 5. Delete the old credential after observation
+
+If you regenerated instead of deleting, confirm nothing still fails with the old value, then delete any leftover token created for the transition.
+
+## 6. Notification duties
+
+If Droplets or databases with personal data were reachable, assess notice duties under the law that applies to that data.
+
+## Sources
+
+- https://docs.digitalocean.com/reference/api/create-personal-access-token/ (accessed 2026-10-26)

package/runbooks/generic.md

@@ -0,0 +1,31 @@
+# Any other credential
+
+Applies to rules without a provider runbook: `generic-api-key`, `jwt`, `private-key`, `gitlab-pat`, `npm-access-token` and the Slack rules.
+
+## 1. Revoke
+
+Find the provider that issued the value and revoke or disable it there. For a private key, remove its public half from every place that trusts it (`authorized_keys`, deploy keys, certificates). For a JWT signing secret, rotate the secret, which invalidates every token it signed.
+
+## 2. Issue the new credential
+
+Prefer short-lived credentials (OIDC, roles, tokens with an expiry) over long-lived ones, and give the new value only the scope the consumer needs.
+
+## 3. Replace it in every consumer
+
+Update the secret store, CI secrets, `.env` files outside git and every host that had the old value.
+
+## 4. Check for misuse in the exposure window
+
+Read the provider's audit or access log from the first exposure until revocation and look for actions you did not take.
+
+## 5. Delete the old credential after observation
+
+Delete leftover records of the old value once consumers have run without errors for a few days.
+
+## 6. Notification duties
+
+If the credential reached personal data, assess notice duties under the law that applies.
+
+## Sources
+
+- https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html (accessed 2026-10-26)

package/runbooks/github.md

@@ -0,0 +1,32 @@
+# GitHub tokens
+
+Applies to rules `github-pat`, `github-oauth`, `github-app-token`, `github-refresh-token` and `github-fine-grained-pat`.
+
+## 1. Revoke
+
+For a personal access token, go to **Settings** > **Developer settings** > **Personal access tokens** and delete it. For an OAuth or GitHub App token, revoke the authorization under **Settings** > **Applications**, or rotate the app's client secret. A revoked token cannot be restored.
+
+## 2. Issue the new credential
+
+Use the narrowest path that works: `GITHUB_TOKEN` inside Actions, a GitHub App installation token for automation, or a fine-grained personal access token limited to the repositories and permissions the consumer needs, with an expiration date.
+
+## 3. Replace it in every consumer
+
+Update repository and organization secrets, CI variables, local `gh auth` sessions, git remotes that carried the token in the URL (`git remote set-url`) and credential helpers.
+
+## 4. Check for misuse in the exposure window
+
+Check the security log (**Settings** > **Security log**, or the organization audit log) for the window: new deploy keys, new tokens, changed branch protection, pushes and releases you did not make, and repositories made public or transferred.
+
+## 5. Delete the old credential after observation
+
+A deleted token is already gone. If you only reduced an app's access, remove the old installation or secret after a few days without failures.
+
+## 6. Notification duties
+
+If private repositories with personal data or customer code were readable, tell the owners of that data and check contractual and legal duties to notify.
+
+## Sources
+
+- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation (accessed 2026-10-26)
+- https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens (accessed 2026-10-26)

package/runbooks/google.md

@@ -0,0 +1,31 @@
+# Google OAuth client secrets and API keys
+
+Applies to rule `gcp-api-key` and to OAuth client secrets found by the generic rules.
+
+## 1. Revoke
+
+For an API key, open **APIs & Services** > **Credentials** and regenerate or delete the key. For an OAuth client secret, add a new secret to the client, then disable the exposed one.
+
+## 2. Issue the new credential
+
+Restrict a new API key to the APIs it calls and to the referrers, IPs or apps that use it. For OAuth, keep the client and rotate only the secret. For server-to-server access prefer workload identity federation over service account key files.
+
+## 3. Replace it in every consumer
+
+Update the backend configuration, CI secrets and any mobile or web build that embeds the key.
+
+## 4. Check for misuse in the exposure window
+
+Check API usage metrics and billing for the key's project in the window, and Cloud Audit Logs for calls you do not recognize.
+
+## 5. Delete the old credential after observation
+
+Delete the disabled OAuth secret once the new one has served traffic without errors.
+
+## 6. Notification duties
+
+If the client could read user data through granted scopes, assess notice duties toward those users and the regulator.
+
+## Sources
+
+- https://support.google.com/cloud/answer/6158849 (accessed 2026-10-26)

package/runbooks/mailgun.md

@@ -0,0 +1,31 @@
+# Mailgun API keys
+
+Applies to Mailgun keys found by the generic rules (for example a `MAILGUN_KEY` assignment).
+
+## 1. Revoke
+
+In the Mailgun control panel, open **API Security** and delete the exposed account key or domain sending key.
+
+## 2. Issue the new credential
+
+Prefer a domain sending key, which can only send mail for one domain, over an account key. Create an account key only for tools that manage the account, with the narrowest role.
+
+## 3. Replace it in every consumer
+
+Update the application configuration, CI secrets and any SMTP credentials that shared the leak.
+
+## 4. Check for misuse in the exposure window
+
+Review sending logs and events for the window: mail you did not send, new domains, new routes or webhooks, and spikes in bounces or complaints that point to spam sent in your name.
+
+## 5. Delete the old credential after observation
+
+Remove any temporary key created for the switch after a few days without delivery errors.
+
+## 6. Notification duties
+
+If message logs or mailing lists with personal data were readable, assess notice duties. If spam went out under your domain, warn the recipients' contact point and watch your domain reputation.
+
+## Sources
+
+- https://documentation.mailgun.com/docs/mailgun/user-manual/api-key-mgmt/rbac-mgmt (accessed 2026-10-26)

package/runbooks/openai.md

@@ -0,0 +1,31 @@
+# OpenAI API keys
+
+Applies to rule `openai-api-key`.
+
+## 1. Revoke
+
+On the API keys page of the OpenAI platform, revoke the exposed key. Revocation takes effect at once.
+
+## 2. Issue the new credential
+
+Create a project key or a service account key in a project that holds only this application, with spend limits and, where the organization allows it, a maximum key lifetime.
+
+## 3. Replace it in every consumer
+
+Update the secret store, CI secrets and every service that reads `OPENAI_API_KEY`.
+
+## 4. Check for misuse in the exposure window
+
+Review usage per project and per key in the window. Calls or spend you cannot explain mean the key was used by someone else.
+
+## 5. Delete the old credential after observation
+
+Remove any temporary key created for the switch once the new key has run cleanly for a few days.
+
+## 6. Notification duties
+
+If the key could reach stored files, assistants or fine-tuning data with personal data, assess notice duties.
+
+## Sources
+
+- https://developers.openai.com/api/docs/guides/production-best-practices (accessed 2026-10-26)

package/runbooks/stripe.md

@@ -0,0 +1,31 @@
+# Stripe secret and restricted keys
+
+Applies to rule `stripe-access-token`.
+
+## 1. Revoke
+
+On **Developers** > **API keys**, open the menu next to the key and choose **Roll key** with expiration **Now**, or **Expire key**. A rolled key with a later expiration keeps working until then, so choose **Now** for a leaked key.
+
+## 2. Issue the new credential
+
+Create a restricted key (`rk_live_`) with only the permissions the integration needs and attach an access policy (IP addresses or allowed networks) so the key works only from your servers.
+
+## 3. Replace it in every consumer
+
+Update the secret store or environment of every backend, worker and CI job. Webhook signing secrets are separate; roll them too if they were in the same file.
+
+## 4. Check for misuse in the exposure window
+
+Open the request logs for the old key in Workbench and review the window: refunds, payouts, transfers, changes to payout bank accounts, new webhook endpoints and customer data exports.
+
+## 5. Delete the old credential after observation
+
+If you rolled with a delay, confirm the old key's request volume stayed at zero, then let it expire or expire it now.
+
+## 6. Notification duties
+
+Card data never passes through your keys, but customer names, emails and addresses do. If they were read, assess notice duties under the law that applies and tell Stripe support about suspicious activity.
+
+## Sources
+
+- https://docs.stripe.com/keys (accessed 2026-10-26)