@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.
- package/README.md +66 -0
- package/THIRD_PARTY_NOTICES.md +12 -9
- package/esm/src/cli/externalSkills.d.ts.map +1 -1
- package/esm/src/cli/externalSkills.js +25 -20
- package/esm/src/cli/mod.d.ts +117 -1
- package/esm/src/cli/mod.d.ts.map +1 -1
- package/esm/src/cli/mod.js +1368 -44
- package/esm/src/cli/projectSkills.d.ts +10 -3
- package/esm/src/cli/projectSkills.d.ts.map +1 -1
- package/esm/src/cli/projectSkills.js +173 -49
- package/esm/src/cli/vercelBuildEnv.d.ts +28 -0
- package/esm/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/esm/src/cli/vercelBuildEnv.js +120 -30
- package/esm/src/next/secrets/mod.d.ts +108 -0
- package/esm/src/next/secrets/mod.d.ts.map +1 -0
- package/esm/src/next/secrets/mod.js +176 -0
- package/esm/src/secrets/encoding.d.ts +32 -0
- package/esm/src/secrets/encoding.d.ts.map +1 -0
- package/esm/src/secrets/encoding.js +87 -0
- package/esm/src/secrets/errors.d.ts +45 -0
- package/esm/src/secrets/errors.d.ts.map +1 -0
- package/esm/src/secrets/errors.js +39 -0
- package/esm/src/secrets/fingerprint.d.ts +43 -0
- package/esm/src/secrets/fingerprint.d.ts.map +1 -0
- package/esm/src/secrets/fingerprint.js +87 -0
- package/esm/src/secrets/frame.d.ts +34 -0
- package/esm/src/secrets/frame.d.ts.map +1 -0
- package/esm/src/secrets/frame.js +86 -0
- package/esm/src/secrets/keyring.d.ts +62 -0
- package/esm/src/secrets/keyring.d.ts.map +1 -0
- package/esm/src/secrets/keyring.js +160 -0
- package/esm/src/secrets/legacy.d.ts +60 -0
- package/esm/src/secrets/legacy.d.ts.map +1 -0
- package/esm/src/secrets/legacy.js +147 -0
- package/esm/src/secrets/maintenance.d.ts +173 -0
- package/esm/src/secrets/maintenance.d.ts.map +1 -0
- package/esm/src/secrets/maintenance.js +315 -0
- package/esm/src/secrets/mod.d.ts +6 -0
- package/esm/src/secrets/mod.d.ts.map +1 -0
- package/esm/src/secrets/mod.js +5 -0
- package/esm/src/secrets/secrets.d.ts +192 -0
- package/esm/src/secrets/secrets.d.ts.map +1 -0
- package/esm/src/secrets/secrets.js +528 -0
- package/package.json +50 -2
- package/script/src/cli/externalSkills.d.ts.map +1 -1
- package/script/src/cli/externalSkills.js +25 -20
- package/script/src/cli/mod.d.ts +117 -1
- package/script/src/cli/mod.d.ts.map +1 -1
- package/script/src/cli/mod.js +1372 -41
- package/script/src/cli/projectSkills.d.ts +10 -3
- package/script/src/cli/projectSkills.d.ts.map +1 -1
- package/script/src/cli/projectSkills.js +173 -49
- package/script/src/cli/vercelBuildEnv.d.ts +28 -0
- package/script/src/cli/vercelBuildEnv.d.ts.map +1 -1
- package/script/src/cli/vercelBuildEnv.js +121 -30
- package/script/src/next/secrets/mod.d.ts +108 -0
- package/script/src/next/secrets/mod.d.ts.map +1 -0
- package/script/src/next/secrets/mod.js +218 -0
- package/script/src/secrets/encoding.d.ts +32 -0
- package/script/src/secrets/encoding.d.ts.map +1 -0
- package/script/src/secrets/encoding.js +95 -0
- package/script/src/secrets/errors.d.ts +45 -0
- package/script/src/secrets/errors.d.ts.map +1 -0
- package/script/src/secrets/errors.js +45 -0
- package/script/src/secrets/fingerprint.d.ts +43 -0
- package/script/src/secrets/fingerprint.d.ts.map +1 -0
- package/script/src/secrets/fingerprint.js +92 -0
- package/script/src/secrets/frame.d.ts +34 -0
- package/script/src/secrets/frame.d.ts.map +1 -0
- package/script/src/secrets/frame.js +91 -0
- package/script/src/secrets/keyring.d.ts +62 -0
- package/script/src/secrets/keyring.d.ts.map +1 -0
- package/script/src/secrets/keyring.js +202 -0
- package/script/src/secrets/legacy.d.ts +60 -0
- package/script/src/secrets/legacy.d.ts.map +1 -0
- package/script/src/secrets/legacy.js +186 -0
- package/script/src/secrets/maintenance.d.ts +173 -0
- package/script/src/secrets/maintenance.d.ts.map +1 -0
- package/script/src/secrets/maintenance.js +323 -0
- package/script/src/secrets/mod.d.ts +6 -0
- package/script/src/secrets/mod.d.ts.map +1 -0
- package/script/src/secrets/mod.js +24 -0
- package/script/src/secrets/secrets.d.ts +192 -0
- package/script/src/secrets/secrets.d.ts.map +1 -0
- package/script/src/secrets/secrets.js +532 -0
- package/skills/loom/SKILL.md +79 -222
- package/skills/loom/references/dependency-upgrades.md +26 -0
- package/skills/loom/references/local-development.md +157 -0
- package/skills/loom/references/release-safety.md +118 -0
- package/skills/loom/references/release-trusted-sources.md +55 -0
- package/skills/loom/references/tools-and-skills.md +83 -0
- package/skills/loom-api-keys/SKILL.md +1 -1
- package/skills/loom-auth/SKILL.md +7 -60
- package/skills/loom-auth/references/secrets-and-rotation.md +61 -0
- package/skills/loom-db/SKILL.md +4 -79
- package/skills/loom-files/SKILL.md +4 -2
- package/skills/loom-files/references/provider-configuration.md +150 -0
- package/skills/loom-jobs/SKILL.md +9 -8
- package/skills/loom-lingui/SKILL.md +5 -3
- package/skills/loom-secrets/SKILL.md +266 -0
- package/skills/loom-torvalds-review/SKILL.md +9 -6
- package/skills/loom-torvalds-review/references/context-profiles.md +2 -1
- 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:
|
|
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), **
|
|
201
|
-
|
|
202
|
-
casting/checking boilerplate from the
|
|
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
|
|
205
|
-
|
|
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
|
|
209
|
-
|
|
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:
|
|
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`
|
|
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`,
|
|
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:
|
|
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
|
-
|
|
24
|
-
|
|
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.
|
|
80
|
-
|
|
81
|
-
|
|
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
|
|
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
|
|
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.
|
|
22
|
-
formatting/lint, typecheck, tests, build, and
|
|
23
|
-
existing warnings and flaky behavior so they
|
|
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
|
-
|
|
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.
|
|
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
|