@gadicc/loom 1.35.3 → 1.37.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (103) hide show
  1. package/README.md +66 -0
  2. package/THIRD_PARTY_NOTICES.md +12 -9
  3. package/esm/src/cli/externalSkills.d.ts.map +1 -1
  4. package/esm/src/cli/externalSkills.js +25 -20
  5. package/esm/src/cli/mod.d.ts +117 -1
  6. package/esm/src/cli/mod.d.ts.map +1 -1
  7. package/esm/src/cli/mod.js +1368 -44
  8. package/esm/src/cli/projectSkills.d.ts +10 -3
  9. package/esm/src/cli/projectSkills.d.ts.map +1 -1
  10. package/esm/src/cli/projectSkills.js +173 -49
  11. package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
  12. package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
  13. package/esm/src/cli/vercelBuildEnv.js +120 -30
  14. package/esm/src/next/secrets/mod.d.ts +108 -0
  15. package/esm/src/next/secrets/mod.d.ts.map +1 -0
  16. package/esm/src/next/secrets/mod.js +176 -0
  17. package/esm/src/secrets/encoding.d.ts +32 -0
  18. package/esm/src/secrets/encoding.d.ts.map +1 -0
  19. package/esm/src/secrets/encoding.js +87 -0
  20. package/esm/src/secrets/errors.d.ts +45 -0
  21. package/esm/src/secrets/errors.d.ts.map +1 -0
  22. package/esm/src/secrets/errors.js +39 -0
  23. package/esm/src/secrets/fingerprint.d.ts +43 -0
  24. package/esm/src/secrets/fingerprint.d.ts.map +1 -0
  25. package/esm/src/secrets/fingerprint.js +87 -0
  26. package/esm/src/secrets/frame.d.ts +34 -0
  27. package/esm/src/secrets/frame.d.ts.map +1 -0
  28. package/esm/src/secrets/frame.js +86 -0
  29. package/esm/src/secrets/keyring.d.ts +62 -0
  30. package/esm/src/secrets/keyring.d.ts.map +1 -0
  31. package/esm/src/secrets/keyring.js +160 -0
  32. package/esm/src/secrets/legacy.d.ts +60 -0
  33. package/esm/src/secrets/legacy.d.ts.map +1 -0
  34. package/esm/src/secrets/legacy.js +147 -0
  35. package/esm/src/secrets/maintenance.d.ts +173 -0
  36. package/esm/src/secrets/maintenance.d.ts.map +1 -0
  37. package/esm/src/secrets/maintenance.js +315 -0
  38. package/esm/src/secrets/mod.d.ts +6 -0
  39. package/esm/src/secrets/mod.d.ts.map +1 -0
  40. package/esm/src/secrets/mod.js +5 -0
  41. package/esm/src/secrets/secrets.d.ts +192 -0
  42. package/esm/src/secrets/secrets.d.ts.map +1 -0
  43. package/esm/src/secrets/secrets.js +528 -0
  44. package/package.json +50 -2
  45. package/script/src/cli/externalSkills.d.ts.map +1 -1
  46. package/script/src/cli/externalSkills.js +25 -20
  47. package/script/src/cli/mod.d.ts +117 -1
  48. package/script/src/cli/mod.d.ts.map +1 -1
  49. package/script/src/cli/mod.js +1372 -41
  50. package/script/src/cli/projectSkills.d.ts +10 -3
  51. package/script/src/cli/projectSkills.d.ts.map +1 -1
  52. package/script/src/cli/projectSkills.js +173 -49
  53. package/script/src/cli/vercelBuildEnv.d.ts +28 -0
  54. package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
  55. package/script/src/cli/vercelBuildEnv.js +121 -30
  56. package/script/src/next/secrets/mod.d.ts +108 -0
  57. package/script/src/next/secrets/mod.d.ts.map +1 -0
  58. package/script/src/next/secrets/mod.js +218 -0
  59. package/script/src/secrets/encoding.d.ts +32 -0
  60. package/script/src/secrets/encoding.d.ts.map +1 -0
  61. package/script/src/secrets/encoding.js +95 -0
  62. package/script/src/secrets/errors.d.ts +45 -0
  63. package/script/src/secrets/errors.d.ts.map +1 -0
  64. package/script/src/secrets/errors.js +45 -0
  65. package/script/src/secrets/fingerprint.d.ts +43 -0
  66. package/script/src/secrets/fingerprint.d.ts.map +1 -0
  67. package/script/src/secrets/fingerprint.js +92 -0
  68. package/script/src/secrets/frame.d.ts +34 -0
  69. package/script/src/secrets/frame.d.ts.map +1 -0
  70. package/script/src/secrets/frame.js +91 -0
  71. package/script/src/secrets/keyring.d.ts +62 -0
  72. package/script/src/secrets/keyring.d.ts.map +1 -0
  73. package/script/src/secrets/keyring.js +202 -0
  74. package/script/src/secrets/legacy.d.ts +60 -0
  75. package/script/src/secrets/legacy.d.ts.map +1 -0
  76. package/script/src/secrets/legacy.js +186 -0
  77. package/script/src/secrets/maintenance.d.ts +173 -0
  78. package/script/src/secrets/maintenance.d.ts.map +1 -0
  79. package/script/src/secrets/maintenance.js +323 -0
  80. package/script/src/secrets/mod.d.ts +6 -0
  81. package/script/src/secrets/mod.d.ts.map +1 -0
  82. package/script/src/secrets/mod.js +24 -0
  83. package/script/src/secrets/secrets.d.ts +192 -0
  84. package/script/src/secrets/secrets.d.ts.map +1 -0
  85. package/script/src/secrets/secrets.js +532 -0
  86. package/skills/loom/SKILL.md +79 -222
  87. package/skills/loom/references/dependency-upgrades.md +26 -0
  88. package/skills/loom/references/local-development.md +157 -0
  89. package/skills/loom/references/release-safety.md +118 -0
  90. package/skills/loom/references/release-trusted-sources.md +55 -0
  91. package/skills/loom/references/tools-and-skills.md +83 -0
  92. package/skills/loom-api-keys/SKILL.md +1 -1
  93. package/skills/loom-auth/SKILL.md +7 -60
  94. package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
  95. package/skills/loom-db/SKILL.md +4 -79
  96. package/skills/loom-files/SKILL.md +4 -2
  97. package/skills/loom-files/references/provider-configuration.md +150 -0
  98. package/skills/loom-jobs/SKILL.md +9 -8
  99. package/skills/loom-lingui/SKILL.md +5 -3
  100. package/skills/loom-secrets/SKILL.md +266 -0
  101. package/skills/loom-torvalds-review/SKILL.md +9 -6
  102. package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
  103. package/skills/upgrade-deps/SKILL.md +15 -7
@@ -0,0 +1,150 @@
1
+ # Loom file provider configuration
2
+
3
+ ## Cloudflare R2 Provisioning
4
+
5
+ Prerequisites:
6
+
7
+ - Wrangler: on Arch, install the official `wrangler` package with
8
+ `sudo pacman -S wrangler`, then run `wrangler login`. Do not assume optional
9
+ login flags from newer Wrangler documentation exist in the packaged version;
10
+ check `wrangler login --help` before using one.
11
+ - Vercel CLI: install the `vercel` npm package globally with the package manager
12
+ used for global Node tools, run `vercel login` if needed, and run
13
+ `vercel link` in the consumer project.
14
+ - MinIO client for local provisioning: on Arch, install the official
15
+ `minio-client` package; its executable is `mcli` (`mc` elsewhere). The MinIO
16
+ server can already be managed separately.
17
+
18
+ The AWS CLI is not required. Before changing real infrastructure, verify both
19
+ accounts with `wrangler whoami --json` and `vercel whoami`. Setup will also
20
+ preflight authentication and project linking before it creates a bucket.
21
+
22
+ After `loom add files`, run:
23
+
24
+ ```sh
25
+ loom files r2 setup --account-id <cloudflare-account-id>
26
+ ```
27
+
28
+ The command requires authenticated Wrangler and Vercel CLIs plus a Vercel-linked
29
+ consumer project. It defaults to two private buckets,
30
+ `<project>-files-production` and `<project>-files-preview`, so preview activity
31
+ cannot mutate production objects. When Wrangler exposes more than one account,
32
+ Loom requires an explicit `--account-id`; `--cloudflare-profile` can select a
33
+ Wrangler auth profile.
34
+
35
+ Loom persists the stable Cloudflare account ID in `loom.json`, but intentionally
36
+ does not persist the developer-specific profile name. Pass the profile flag per
37
+ command or bind that profile to the consumer project with
38
+ `wrangler auth
39
+ activate`; named profiles require a Wrangler release that
40
+ provides the experimental `wrangler auth` profile commands.
41
+
42
+ Provisioning is additive and rerunnable. It reuses compatible buckets, never
43
+ deletes buckets, never enables public development URLs or custom domains, and
44
+ never rotates credentials. If provisioning stops after bucket creation,
45
+ `loom.json` records a partial state and the next setup run reuses those buckets.
46
+ Use `--repair` only to accept declared non-secret configuration drift. Existing
47
+ custom storage modules are preserved rather than overwritten.
48
+
49
+ Create one Cloudflare R2 Object Read & Write API token restricted to the two
50
+ selected buckets. Loom does not create this token automatically because doing so
51
+ would require a broader Cloudflare API-token-management permission. Then run:
52
+
53
+ ```sh
54
+ loom files r2 setup --account-id <cloudflare-account-id> --configure-secrets
55
+ ```
56
+
57
+ Vercel prompts for each missing access-key id and secret, marks the values
58
+ sensitive, and writes them only to Production and Preview. Loom does not
59
+ receive, print, persist, or replace those values. Without `--configure-secrets`,
60
+ setup finishes with exit status 2 and an actionable `credentials-required` state
61
+ until the variables exist. Non-secret Vercel values are maintained under these
62
+ names:
63
+
64
+ - `FILES_S3_BUCKET`
65
+ - `FILES_S3_ENDPOINT`
66
+ - `FILES_S3_FORCE_PATH_STYLE=false` by default, or the explicit provider
67
+ `forcePathStyle` value
68
+ - `FILES_S3_REGION=auto`
69
+ - `FILES_STORAGE_PROVIDER=cloudflare-r2`
70
+
71
+ Setup adds missing non-secret values with `--no-sensitive` (Vercel CLI 54 or
72
+ newer), because the CLI otherwise stores a Production or Preview value as a
73
+ Secret, which `loom files r2 check` and release env policies cannot read back.
74
+ `--repair` updates drifted values in place and keeps their Vercel type, so it
75
+ cannot fix a value an earlier setup stored as a Secret. Setup and
76
+ `loom check --network` name any such values instead of suggesting `--repair`;
77
+ remove them in Vercel, then rerun setup to add them back as readable values.
78
+
79
+ The sensitive variables are `FILES_S3_ACCESS_KEY_ID` and
80
+ `FILES_S3_SECRET_ACCESS_KEY`. Rerun setup to repair missing non-secret values or
81
+ prompt only for missing secrets. Run `loom files r2 check` or
82
+ `loom check --network` afterward to verify remote state and environment scoping.
83
+
84
+ R2 defaults to server-mediated uploads and downloads, with no browser-direct
85
+ policy or CORS changes. File size, allowed types, metadata policy, malware
86
+ scanning, retention, and deletion remain app-owned concerns.
87
+
88
+ ### Private signed browser uploads
89
+
90
+ Apps with a reviewed signer and server-side finalization can explicitly declare
91
+ private presigned PUTs in `features.files.config.storage.provider`:
92
+
93
+ ```json
94
+ {
95
+ "accessMode": "private",
96
+ "publicUrl": null,
97
+ "directBrowserAccess": true,
98
+ "forcePathStyle": true,
99
+ "directUpload": {
100
+ "kind": "presigned-put",
101
+ "origins": {
102
+ "production": ["https://example.com"],
103
+ "preview": ["https://preview.example.com"]
104
+ },
105
+ "allowedHeaders": [
106
+ "content-type",
107
+ "if-none-match",
108
+ "x-amz-checksum-sha256"
109
+ ],
110
+ "maxAgeSeconds": 300
111
+ }
112
+ }
113
+ ```
114
+
115
+ This is a provider fragment, not a complete manifest. Include every header sent
116
+ by the actual browser signer, including app-specific provenance headers. Origins
117
+ must be unique exact HTTPS origins without paths, trailing slashes, credentials,
118
+ query strings, fragments, or wildcards. Header names must be unique lowercase
119
+ names without wildcards. The cache age is an integer from 0 to 86400 seconds.
120
+ Omitting `forcePathStyle` preserves the existing false default independently of
121
+ the direct-upload choice; explicitly set it to match the reviewed adapter.
122
+
123
+ The app still authorizes issuance, signs a bounded destination/size/digest and
124
+ expiry, validates uploaded bytes, and authorizes publication. CORS is a browser
125
+ permission, not authorization. Signed PUTs do not enable public downloads:
126
+ public development URLs and custom domains remain prohibited. Keep protected
127
+ download authorization and cache behavior in the app.
128
+
129
+ Setup preserves a valid declared policy and explicit addressing mode. It never
130
+ applies CORS. For a newly provisioned bucket with a declared direct-upload
131
+ policy, setup records `buckets-ready` and stops until the exact CORS policy has
132
+ been reviewed and applied separately. Use
133
+ `wrangler r2 bucket cors set <bucket>
134
+ --file <reviewed-policy.json>`
135
+ deliberately; that command replaces the complete policy. Then rerun setup and
136
+ `loom files r2 check`.
137
+
138
+ Checks require exactly one rule per bucket: the declared origins, PUT only,
139
+ exact declared headers, no exposed response headers, and the declared cache age.
140
+ A deliberate shared bucket uses the union of both environments' origins.
141
+ Missing/extra rules, wildcards, drift, and inaccessible or unrecognized CORS
142
+ output fail the check. No checker changes provider configuration.
143
+
144
+ Wrangler 4.112 has no JSON flag for `r2 bucket cors list`. Loom requests its
145
+ banner-free, color-free labelled output and compares all five permission fields;
146
+ rule IDs are not exposed by that command and do not grant access. Unknown output
147
+ formats remain unverified. Default server-mediated configurations do not gain a
148
+ new CORS dependency. Existing private endpoint/domain checks still run in both
149
+ modes. This policy check does not prove byte enforcement, app authorization, or
150
+ a complete private runtime; verify those in the consumer separately.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: loom-jobs
3
- description: Use when the task mentions the loom jobs feature, src/jobs or jobs catalogs, /admin/jobs pages or route handlers, createJobsListPage, createJobsRunPage, createJobsRouteHandler, direct runners, or repairing loom-managed jobs wrappers in a consuming app.
3
+ description: Adopt, repair or change Loom job catalogs, runners, HTTP routes and admin UI in a consumer app.
4
4
  ---
5
5
 
6
6
  # Loom Jobs
@@ -197,16 +197,17 @@ When adding or upgrading a job:
197
197
  ```
198
198
  - **Upgrade Old-Style Params**: If you are working on an existing job that
199
199
  accesses parameters from raw query/string objects (e.g. using
200
- `Number(params.count)` or `params.resetStale === "true"` manually), **upgrade
201
- it** to use declarative `params` metadata. This removes manual type
202
- casting/checking boilerplate from the handler and improves safety.
200
+ `Number(params.count)` or `params.resetStale === "true"` manually), **propose
201
+ migration when parameter handling is in scope** to use declarative `params`
202
+ metadata. This removes manual type casting/checking boilerplate from the
203
+ handler and improves safety.
203
204
  - **Scaffolding and UI**: Declaring parameters will automatically:
204
- 1. Render a premium parameters form on the Next.js admin `/run` page with
205
- hover tooltips and default placeholders.
205
+ 1. Render a parameters form on the Next.js admin `/run` page with hover
206
+ tooltips and default placeholders.
206
207
  2. Perform automatic type validation on Next.js API routes (returning
207
208
  `400 Bad Request` on invalid inputs).
208
- 3. Validate options and print a beautiful `--help` option menu in the CLI
209
- `jobDirect` runner.
209
+ 3. Validate options and print a `--help` option menu in the CLI `jobDirect`
210
+ runner.
210
211
 
211
212
  ## Verification
212
213
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: loom-lingui
3
- description: Manage Lingui catalog tooling in Loom consumer projects. Use when adding, migrating, reviewing, or repairing Lingui dependencies, catalog modes, extraction and compilation tasks, generated-catalog ignores, or Next.js loader and SWC wiring.
3
+ description: Adopt, repair or change Lingui catalog compilation, loader wiring and tasks in a Loom consumer.
4
4
  ---
5
5
 
6
6
  # Loom Lingui
@@ -12,7 +12,8 @@ generated JavaScript catalogs.
12
12
 
13
13
  1. Inspect `loom.json`, the Lingui config, dependency and task config,
14
14
  `.gitignore`, Next config, and runtime catalog imports.
15
- 2. Run `loom add lingui` to adopt or repair the managed baseline.
15
+ 2. Run `loom add lingui` only when adoption or managed-baseline repair is in
16
+ scope. Inspection or translation-content work does not require adoption.
16
17
  3. Confirm the recorded catalog mode matches runtime imports:
17
18
  - Use `precompile` when runtime code imports generated `.js` catalogs. Ensure
18
19
  the compile task runs before the framework build.
@@ -22,7 +23,8 @@ generated JavaScript catalogs.
22
23
  4. Keep generated catalog patterns ignored. If generated files are already
23
24
  tracked, propose removing only those files from the Git index while leaving
24
25
  local build output intact.
25
- 5. Run `loom check`, the Lingui compile task, and the production build.
26
+ 5. Use affected catalog checks during edits. Run `loom check`, compilation and a
27
+ production build when changing build/loader wiring or preparing release.
26
28
 
27
29
  ## Boundaries
28
30
 
@@ -0,0 +1,266 @@
1
+ ---
2
+ name: loom-secrets
3
+ description: Use when the task touches the Loom secrets feature, @gadicc/loom/secrets or @gadicc/loom/next/secrets, sealed strings (ls1.), keyed fingerprints (lm1.), LOOM_SECRETS_KEY_ variables, key rotation, assertReady, reseal or verify jobs, or storing third-party credentials, tokens or TOTP seeds that the app must later read back.
4
+ ---
5
+
6
+ # Loom Secrets
7
+
8
+ Use this skill when an app stores values it must later use in clear: provider
9
+ passwords and API keys, saved sessions, TOTP seeds, short-lived tokens handed to
10
+ a caller, or fingerprints for matching a value without storing it.
11
+
12
+ Passwords the app only verifies are not secrets in this sense. Hash them.
13
+
14
+ ## Start here
15
+
16
+ 1. Read `loom.json` and inspect `features.secrets.config`: the wrapper module,
17
+ the locations module, the variable names and the production key list.
18
+ 2. Read the wrapper module. Every purpose the app uses is declared there.
19
+ 3. Read the locations module. Every column that holds a sealed string must be
20
+ declared there, or it is not reported, verified or resealed.
21
+
22
+ ## What it protects, and what it does not
23
+
24
+ - It protects against the database being read on its own: a dump, a backup, a
25
+ branch, console access.
26
+ - It makes the app refuse a value presented for a different purpose, owner or
27
+ bound destination.
28
+ - It does **not** protect against code running in the app, or anyone who can
29
+ deploy to the project or read its environment.
30
+ - It does **not** contain someone who can edit the rows the app trusts for where
31
+ to send a credential, unless that destination is in the binding.
32
+ - It does **not** stop an older valid value of the same row being put back.
33
+
34
+ Do not describe it as more than this in an app's docs or UI.
35
+
36
+ ## Never do these
37
+
38
+ - **Never run `loom secrets keygen` for a production key, and never ask for its
39
+ output.** A production key must exist in exactly two places: the operator's
40
+ password manager and the deployment platform. An agent's transcript is a
41
+ third. Ask the operator to run it in their own terminal, then continue from
42
+ the fingerprint, which is not secret. The same goes for
43
+ `loom secrets fingerprint` and `loom secrets push`, which prompt for a key.
44
+ All three refuse to run when they detect a CI or agent session or a missing
45
+ terminal. That is a guardrail, not a guarantee: do not look for a way to
46
+ satisfy it. The rule holds whether or not the command would run.
47
+ - **Never pass a key as a command-line argument**, to `fingerprint` or anything
48
+ else. A key typed there is in shell history: treat it as exposed and rotate.
49
+ - **Never read, print, log or commit a key**: not `.env.local`, not a
50
+ `LOOM_SECRETS_KEY_*` or `CRYPTO_KEY_*` value, not in a test, not in
51
+ `loom.json`. `loom.json` holds fingerprints only.
52
+ - **Never set `allowDuringBuild` to make a failing build pass.** Make the route
53
+ dynamic.
54
+ - **Never pass `allowUnverifiedKeys` to a reseal against a production
55
+ database**, and never set `allowUnverifiedProduction` to make a health check
56
+ pass. Both exist because moving rows onto a key that was never shown to match
57
+ its fingerprint, and later retiring the old key, loses every row.
58
+ - **Never write another format beside it**, and never write the legacy
59
+ `(value, iv)` format: `@gadicc/loom/secrets/legacy` is read-only on purpose.
60
+ - **Never delete an entry from the key list or reuse its version number.**
61
+
62
+ ## Using it
63
+
64
+ ```ts
65
+ // the wrapper module
66
+ import { createNextSecrets } from "@gadicc/loom/next/secrets";
67
+ import loomManifest from "../loom.json";
68
+
69
+ const config = loomManifest.features.secrets.config;
70
+ export const secrets = createNextSecrets({
71
+ expectedKeys: config.keys,
72
+ variables: config.env,
73
+ });
74
+ export const forumApiKey = secrets.purpose("temple-forum.api-key");
75
+ ```
76
+
77
+ ```ts
78
+ await forumApiKey.seal(value, { temple: templeId, origin });
79
+ await forumApiKey.tryOpen(stored, { temple: templeId, origin });
80
+ ```
81
+
82
+ - **One purpose per kind of value.** Names are permanent identifiers:
83
+ `connection.password`, not `password`.
84
+ - **Always bind.** Bind to the owner (a row id, and the user where there is one)
85
+ and, where a secret has one stable destination, to that destination. Use
86
+ identifiers the app never transforms: no case folding, no URL tidying.
87
+ - **Changing which fields a purpose is bound to is a new purpose name.**
88
+ Changing the _value_ of a bound field is different: if it can be edited
89
+ without the secret being entered again, open with the old binding and seal
90
+ with the new one inside the same transaction.
91
+ - **Generate ids in the app** when a binding needs the id of a row that is being
92
+ inserted.
93
+ - **`open` throws one opaque error.** Its `reason` is for server logs. Never
94
+ show it to a user or return it from an API. Use `tryOpen` when "unreadable" is
95
+ a state the UI handles.
96
+ - **Parse JSON with `openJson`**, not `JSON.parse(await open(…))`: a
97
+ `SyntaxError` message quotes the plaintext.
98
+ - **Tokens** are a purpose with `ttlSeconds` and a small `maxLength`. Loom
99
+ enforces the lifetime. Replay, revocation and what the token authorises are
100
+ the app's job, so keep checking kind, user and session inside the payload.
101
+ - **Do not log** plaintext, sealed strings or bindings.
102
+
103
+ ### Next.js
104
+
105
+ - Secrets are unavailable while `next build` prerenders. Every operation,
106
+ including `tryOpen`, rejects with `SecretsBuildPhaseError`. A route that uses
107
+ secrets must be dynamic.
108
+ - The refusal covers the build only. A route that caches its output at run time
109
+ (`revalidate`, `use cache`) caches whatever it decrypted. Do not cache a
110
+ response that contains a secret.
111
+ - The key list that applies comes from `LOOM_SECRETS_ENVIRONMENT`, then
112
+ `VERCEL_ENV`. A host other than Vercel must set
113
+ `LOOM_SECRETS_ENVIRONMENT=production` in the platform's own environment, which
114
+ takes precedence over `.env` files. To run a production build locally, set it
115
+ to `development` in `.env.local`; `loom add secrets` writes that.
116
+ - For that reason `.env*.local` files must be excluded from container images and
117
+ deployments (`.dockerignore`, the platform's ignore file). A deployed
118
+ `.env.local` would otherwise declare the host to be `development`.
119
+ - If `LOOM_SECRETS_ENVIRONMENT` and `VERCEL_ENV` name different environments,
120
+ every operation is refused. Fix the variable; do not pass an `environment`
121
+ option to silence it.
122
+ - `loom.json`'s `env` section holds variable names and goes in `variables`. The
123
+ option for the object keys are read from is `keysEnv`, which an app rarely
124
+ needs; there is no `env` option.
125
+ - `loom check` requires the secrets module of a Next.js app to import
126
+ `@gadicc/loom/next/secrets`. The core `@gadicc/loom/secrets` has no build
127
+ refusal and no environment-selected key list.
128
+
129
+ ### Health check
130
+
131
+ Call `secrets.assertReady()` from a dynamic route and hit it from the release
132
+ smoke test. In production it rejects unless every recorded key is present and
133
+ matches its fingerprint and the pointer is on the active key. That is the only
134
+ proof that the deployed key is the one in the password manager. If the app
135
+ reports the result, require `verified === true` in production.
136
+
137
+ ### Keyed fingerprints
138
+
139
+ `mac(text, binding)` is deterministic and uses the text exactly as given.
140
+
141
+ - A fingerprint is **not** a stable lookup key across a rotation. To find a
142
+ stored entry, compare with `macMatches(stored, text, binding)`, or compute
143
+ under each key still in use with `mac(text, binding, { keyId })`.
144
+ - When `macNeedsRefresh(stored)` is true and the text is at hand, store a new
145
+ fingerprint.
146
+ - Seal the input beside the value it indexes, so the fingerprint can be
147
+ recomputed. Otherwise the old key can never be retired.
148
+ - Equal text under an equal binding gives equal fingerprints, visible to anyone
149
+ who can read them. Put an owner in the binding where that matters.
150
+
151
+ ## Keys
152
+
153
+ ```
154
+ LOOM_SECRETS_KEY_1=… # write-only secret, Production only
155
+ LOOM_SECRETS_ACTIVE_KEY=1 # readable
156
+ ```
157
+
158
+ - One variable per key version and a required pointer. Different keys per
159
+ environment. Never share a key between apps.
160
+ - Production fingerprints are recorded in `loom.json` with a state: `active`,
161
+ `decrypt-only` or `retired`. Use `loom secrets activate` and
162
+ `loom secrets retire` to change states rather than editing by hand.
163
+ - On a project linked to Vercel (`.vercel/project.json`), `keygen` offers to add
164
+ the new key to Vercel Production as a Secret, and the pointer when the key is
165
+ the active one. It first has the operator paste the key back from their
166
+ password manager and checks it against the recorded fingerprint, so the saved
167
+ copy is proven before Vercel has one. `loom secrets push <id>` does the same
168
+ later for a recorded key, and `loom secrets activate <id>` offers to move the
169
+ Vercel pointer before it changes `loom.json`. `--vercel` does it without the
170
+ first question and `--no-vercel` never. When telling an operator to run
171
+ `keygen`, mention the offer. An agent may run `activate --vercel` only when
172
+ the user asked for that production change; without the flag, an agent session
173
+ changes nothing on Vercel.
174
+ - Development keys are written to `.env.local` by `loom add secrets` and are not
175
+ recorded. `vercel env pull` rewrites `.env.local` and can drop them; run
176
+ `loom add secrets` again. Locally sealed rows are then unreadable, which is
177
+ fine for development data.
178
+
179
+ ### Rotation
180
+
181
+ 1. Operator: `loom secrets keygen`, which records the new key as `decrypt-only`.
182
+ Save the key and fingerprint in the password manager.
183
+ 2. Operator: add `LOOM_SECRETS_KEY_<n+1>` to the platform from the
184
+ password-manager copy, as a write-only secret for Production only (on Vercel,
185
+ accept `keygen`'s offer or run `loom secrets push <n+1>`). Deploy. The health
186
+ check must pass.
187
+ 3. Move the pointer, in this order. Operator: set
188
+ `LOOM_SECRETS_ACTIVE_KEY=<n+1>` on the platform **first** (on Vercel,
189
+ `loom secrets activate <n+1>` offers to do this before it changes
190
+ `loom.json`). Then `loom secrets activate <n+1>`, run
191
+ `loom check --production`, and push the `loom.json` change, so the deployment
192
+ that carries the new list is built with the new pointer. In the other order,
193
+ a deployment with the new list and the old pointer fails every `seal`,
194
+ `reseal` and `mac` (opens still work). Then delete deployments built before
195
+ step 2: an older deployment keeps the environment it was built with and
196
+ cannot read the new rows.
197
+ 4. Run `reseal` (a real run needs `dryRun: false`), then `report`, then
198
+ `verify`.
199
+ 5. Retiring the old key is a separate decision. It is safe only when:
200
+ - `report` shows no row under it, with every location `done`;
201
+ - no keyed fingerprint is still under it (`report` does not count those);
202
+ - expired values under it have been deleted, since they can never be
203
+ resealed;
204
+ - no restorable database backup needs it.
205
+
206
+ Then `loom secrets retire <n>` and deploy that `loom.json` **before**
207
+ removing the variable: while a deployed list still expects the key,
208
+ `assertReady()` fails with "not configured" once the variable is gone. After
209
+ that, remove its variable and delete every deployment built while it was
210
+ active. Keep the list entry and the password-manager copy.
211
+
212
+ After a suspected compromise, also change the stored credentials at their
213
+ providers. Resealing does not un-leak them.
214
+
215
+ ### A key that was recorded but never saved
216
+
217
+ `keygen` records the fingerprint in `loom.json` before the operator has saved
218
+ the key. If the key was lost first (the terminal was closed, the paste failed):
219
+
220
+ 1. Operator: `loom secrets keygen` again. It takes the next version.
221
+ 2. `loom secrets activate <new>`, then deploy it as in the rotation above.
222
+ 3. `loom secrets retire <lost>`.
223
+
224
+ The lost version's entry stays in the list, retired, and fails closed at run
225
+ time. Do not delete the entry or reuse its number. There is no un-retire: a
226
+ retired version cannot be activated again, so retire only a key that is truly
227
+ gone or no longer needed.
228
+
229
+ ## Maintenance
230
+
231
+ - `reportSecretLocations` counts rows per key version without decrypting, so it
232
+ needs no key.
233
+ - `verifySecretLocations` opens every row strictly and names the rows that do
234
+ not open.
235
+ - `resealSecretLocations` moves rows to the active key. It is a dry run unless
236
+ `dryRun: false`. It first runs `assertReady()` for each location's purpose,
237
+ and a real run refuses unless the keys were verified against the recorded
238
+ list.
239
+
240
+ `verify` and `reseal` must run inside the deployed app, behind admin
241
+ authorization, because the keys exist nowhere else.
242
+
243
+ Reading results: a location is finished only when `done` is true. A clean run
244
+ has `failureCount` 0 and, for reseal, `changed` 0; a changed row was left alone
245
+ and is still under its old key, so run again. To continue a run that stopped at
246
+ `maxRows`, pass its results back as `previous`.
247
+
248
+ A location's `write` is one `UPDATE … WHERE` and never an insert. Build a
249
+ location's binding with the same function the app's reader uses.
250
+
251
+ ## What to preserve
252
+
253
+ - Purpose names and bindings of existing data.
254
+ - Every entry in the production key list in `loom.json`.
255
+ - Any `CRYPTO_KEY_<n>` variable an app still reads through the legacy reader.
256
+ - The release policy entries `loom check` asks for: a `keyPattern` requirement
257
+ that keeps the secrets keys Production-only write-only secrets, and a `keys`
258
+ requirement for the pointer variable (`LOOM_SECRETS_ACTIVE_KEY`).
259
+
260
+ ## Verification
261
+
262
+ - Tests inject keys with `staticKeyring({ 1: bytes })` and a clock. Use
263
+ obviously synthetic keys, never a real one.
264
+ - Run `loom check`, and `loom check --production` before a release.
265
+ - After changing where sealed strings are stored, update the locations module
266
+ and run `verify`.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: loom-torvalds-review
3
- description: Context-aware code and design review for Loom consumer projects, adapting the linus-torvalds-skill reviewer method to the actual runtime and product contract. Use when reviewing a diff or pull request, assessing an API or architecture change, checking a refactor or bug fix, challenging a performance claim, or doing the final engineering review of implementation work, especially in Next.js and other web applications.
3
+ description: Review Loom code and designs using the actual product and runtime contracts. Adapts the upstream Torvalds method for web apps, libraries, CLI and native code.
4
4
  ---
5
5
 
6
6
  # Loom Torvalds Review
@@ -20,8 +20,9 @@ corpus-derived severity rates, or Linus Torvalds's persona as universal rules.
20
20
  repository's explicit contract.
21
21
  3. For a code or design review, read
22
22
  `.agents/skills/linus-torvalds-skill/SKILL.md` when it is installed. Treat
23
- its triggers as a source of review questions, not automatic findings. Do not
24
- load or imitate an upstream `soul` or persona file.
23
+ only this entrypoint, not the GLM/Mistral variants or a `soul`/persona file.
24
+ Treat its triggers, verdict tables, decision trees, simplified workflows and
25
+ severity percentages as questions, never automatic findings or binding rules.
25
26
  4. If the upstream skill is not installed, continue with this skill. Mention
26
27
  `loom add skills` only when the missing deeper review catalog materially
27
28
  limits the task.
@@ -76,9 +77,11 @@ kernel convention above security or supported users.
76
77
  4. Check the actual diff for unrelated churn, compatibility changes, hidden
77
78
  costs, unnecessary special cases, inaccurate docs, and missing cleanup
78
79
  created by the change.
79
- 5. Seek proportionate evidence. Reproduce correctness failures; use realistic
80
- measurements for performance claims; run the repository's relevant tests,
81
- typecheck, lint, and build when implementation work is in scope.
80
+ 5. Seek proportionate evidence. Establish correctness failures through a
81
+ concrete source trace or a permitted reproduction; use realistic measurements
82
+ for performance claims; run the repository's relevant tests, typecheck, lint,
83
+ and build when implementation work is in scope. A read-only review does not
84
+ require mutations or extra agents; disclose verification gaps.
82
85
  6. Derive severity from concrete impact and reachability. Ignore the upstream
83
86
  corpus percentages when deciding whether a finding blocks the change.
84
87
 
@@ -84,7 +84,8 @@ same: what real contract or failure mode does this rule protect here?
84
84
  Isolate unavoidable Node or native behavior and test the supported runtimes.
85
85
  - Apply bisectability to the commits that will be shipped. A working tree need
86
86
  not be valid at every keystroke, while each final commit should build and make
87
- coherent sense when the repository requires that history quality.
87
+ coherent sense. Follow Loom's applicable full-suite evidence rule before code
88
+ commits and preserve the repository's stronger build gates.
88
89
  - Require benchmarks only for performance claims or budgets that affect package
89
90
  users. Include startup time, artifact size, throughput, memory, and generated
90
91
  client-bundle impact when relevant.
@@ -10,7 +10,9 @@ prove each meaningful change, and leave intentional deferrals documented.
10
10
 
11
11
  ## 1. Establish the contract
12
12
 
13
- 1. Read repository instructions before changing files.
13
+ 1. Read repository instructions and distinguish an inventory-only request from
14
+ an authorized upgrade. Read-only inventory does not require installs or
15
+ gates.
14
16
  2. Inspect the manifests, lockfiles, dependency-manager declarations, runtime
15
17
  versions, CI workflows, and available verification scripts. Keep the existing
16
18
  dependency manager unless the user explicitly requests a migration.
@@ -18,9 +20,10 @@ prove each meaningful change, and leave intentional deferrals documented.
18
20
  Do not rely on destructive rollback commands in a dirty tree.
19
21
  4. Identify generated files and their source commands. Regenerate them through
20
22
  the project workflow rather than editing them manually.
21
- 5. Run the strongest practical baseline: install or lockfile validation,
22
- formatting/lint, typecheck, tests, build, and project-specific checks. Record
23
- existing warnings and flaky behavior so they are not attributed to upgrades.
23
+ 5. Before implementation, establish the strongest practical baseline: install or
24
+ lockfile validation, formatting/lint, typecheck, tests, build, and
25
+ project-specific checks. Record existing warnings and flaky behavior so they
26
+ are not attributed to upgrades.
24
27
 
25
28
  If the project consumes Loom, use the `loom` skill first, read `loom.json`, use
26
29
  feature skills affected by the upgrade, and include `loom check --production` in
@@ -150,11 +153,16 @@ Follow the repository's commit-message and attribution rules.
150
153
 
151
154
  ## 8. Run the exact-tree final gate
152
155
 
153
- After formatting or commit hooks have finished, verify the exact final tree:
156
+ Format before the final gate. Have evidence for the exact content being
157
+ committed; do not rely on unstaged fixes. Preserve user-owned changes using an
158
+ isolated snapshot when necessary, never an automatic stash or reset.
159
+
160
+ For the final tree:
154
161
 
155
162
  1. Confirm manifest and lockfile consistency across the project or workspace.
156
- 2. Run required generators, lint/format, typecheck, full tests, production
157
- build, and project-specific checks.
163
+ 2. Have passing required generators, lint/format, typecheck, full tests,
164
+ production build, and project-specific checks. Reuse evidence only while its
165
+ inputs are unchanged; edits or hooks that change them invalidate it.
158
166
  3. Inspect the final status and diff for unrelated changes.
159
167
  4. Re-run the outdated inventory when registry access is available.
160
168
  5. Report successful upgrades, migrations, removals, deferred packages with