owenloop 0.5.0 → 0.5.1
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/CHANGELOG.md +45 -0
- package/README.md +137 -35
- package/bin/owenloop.mjs +49 -1
- package/dist/packages/work/src/agent/brief.d.ts +8 -4
- package/dist/packages/work/src/agent/brief.js +7 -3
- package/dist/packages/work/src/agent/loop.d.ts +13 -7
- package/dist/packages/work/src/agent/loop.js +136 -9
- package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
- package/dist/packages/work/src/agent/model-policy.js +138 -0
- package/dist/packages/work/src/bundle/cache.d.ts +7 -5
- package/dist/packages/work/src/bundle/cache.js +20 -6
- package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
- package/dist/packages/work/src/bundle/fetch.js +27 -7
- package/dist/packages/work/src/bundle/types.d.ts +8 -4
- package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
- package/dist/packages/work/src/consumed-verifier.js +205 -0
- package/dist/packages/work/src/exec/instructions.d.ts +99 -0
- package/dist/packages/work/src/exec/instructions.js +323 -0
- package/dist/packages/work/src/exec/loop.d.ts +12 -1
- package/dist/packages/work/src/exec/loop.js +137 -20
- package/dist/packages/work/src/exec/payload.d.ts +29 -0
- package/dist/packages/work/src/exec/payload.js +54 -0
- package/dist/packages/work/src/exec/receipt.d.ts +9 -6
- package/dist/packages/work/src/exec/receipt.js +12 -1
- package/dist/packages/work/src/exec/runner.d.ts +7 -1
- package/dist/packages/work/src/exec/runner.js +74 -3
- package/dist/packages/work/src/harness/child-env.js +7 -0
- package/dist/packages/work/src/harness/claude.d.ts +20 -8
- package/dist/packages/work/src/harness/claude.js +260 -58
- package/dist/packages/work/src/harness/codex.d.ts +5 -4
- package/dist/packages/work/src/harness/codex.js +169 -41
- package/dist/packages/work/src/harness/contract.d.ts +36 -11
- package/dist/packages/work/src/harness/fake.js +1 -0
- package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
- package/dist/packages/work/src/harness/permissions.d.ts +16 -3
- package/dist/packages/work/src/harness/permissions.js +102 -13
- package/dist/packages/work/src/harness/session-store.d.ts +27 -9
- package/dist/packages/work/src/harness/session-store.js +271 -67
- package/dist/packages/work/src/hold/mcp.d.ts +25 -5
- package/dist/packages/work/src/hold/mcp.js +126 -11
- package/dist/packages/work/src/hub/client.d.ts +2 -1
- package/dist/packages/work/src/hub/client.js +14 -1
- package/dist/packages/work/src/hub/types.d.ts +69 -33
- package/dist/packages/work/src/hub/types.js +8 -10
- package/dist/packages/work/src/mcp/server.js +1 -1
- package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
- package/dist/packages/work/src/owenloop-bin.js +18 -0
- package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
- package/dist/packages/work/src/roles/agent-run.js +116 -34
- package/dist/packages/work/src/roles/exec.d.ts +8 -0
- package/dist/packages/work/src/roles/exec.js +27 -2
- package/dist/packages/work/src/roles/hold.d.ts +4 -0
- package/dist/packages/work/src/roles/hold.js +44 -5
- package/dist/packages/work/src/roles/lint.d.ts +3 -4
- package/dist/packages/work/src/roles/lint.js +41 -7
- package/dist/packages/work/src/roles/settings.js +5 -0
- package/dist/packages/work/src/roles/shift.d.ts +1 -0
- package/dist/packages/work/src/roles/shift.js +23 -1
- package/dist/packages/work/src/settings/settings.d.ts +17 -1
- package/dist/packages/work/src/settings/settings.js +39 -0
- package/dist/packages/work/src/shift/loop.d.ts +14 -3
- package/dist/packages/work/src/shift/loop.js +447 -164
- package/dist/packages/work/src/shift/protocol.d.ts +4 -0
- package/dist/packages/work/src/shift/runtime.d.ts +2 -0
- package/dist/packages/work/src/shift/runtime.js +66 -3
- package/dist/packages/work/src/shift/spawn.d.ts +41 -18
- package/dist/packages/work/src/shift/spawn.js +89 -31
- package/dist/packages/work/src/shift/state.d.ts +53 -51
- package/dist/packages/work/src/shift/state.js +325 -102
- package/dist/packages/work/src/submit-proof.d.ts +36 -0
- package/dist/packages/work/src/submit-proof.js +93 -0
- package/dist/src/add.d.ts +64 -259
- package/dist/src/add.js +81 -615
- package/dist/src/archive.d.ts +97 -0
- package/dist/src/archive.js +591 -0
- package/dist/src/bundle/index.d.ts +64 -0
- package/dist/src/bundle/index.js +508 -0
- package/dist/src/bundle/manifest.d.ts +50 -0
- package/dist/src/bundle/manifest.js +435 -0
- package/dist/src/bundle/runtime.d.ts +26 -0
- package/dist/src/bundle/runtime.js +64 -0
- package/dist/src/bundle/tar.d.ts +62 -0
- package/dist/src/bundle/tar.js +238 -0
- package/dist/src/bundle/types.d.ts +105 -0
- package/dist/src/bundle/types.js +21 -0
- package/dist/src/cli.d.ts +90 -20
- package/dist/src/cli.js +2407 -365
- package/dist/src/credentials.d.ts +4 -3
- package/dist/src/credentials.js +21 -19
- package/dist/src/crypto/allowed-signers.d.ts +68 -0
- package/dist/src/crypto/allowed-signers.js +307 -0
- package/dist/src/crypto/canonical.d.ts +8 -0
- package/dist/src/crypto/canonical.js +92 -0
- package/dist/src/crypto/chain.d.ts +65 -0
- package/dist/src/crypto/chain.js +377 -0
- package/dist/src/crypto/dsse.d.ts +209 -0
- package/dist/src/crypto/dsse.js +282 -0
- package/dist/src/crypto/enrollment.d.ts +78 -0
- package/dist/src/crypto/enrollment.js +186 -0
- package/dist/src/crypto/index.d.ts +48 -0
- package/dist/src/crypto/index.js +44 -0
- package/dist/src/crypto/keys.d.ts +258 -0
- package/dist/src/crypto/keys.js +908 -0
- package/dist/src/crypto/org-root.d.ts +33 -0
- package/dist/src/crypto/org-root.js +78 -0
- package/dist/src/crypto/origin-rules.d.ts +56 -0
- package/dist/src/crypto/origin-rules.js +143 -0
- package/dist/src/crypto/policy-floor.d.ts +98 -0
- package/dist/src/crypto/policy-floor.js +353 -0
- package/dist/src/crypto/records.d.ts +316 -0
- package/dist/src/crypto/records.js +157 -0
- package/dist/src/crypto/scope.d.ts +49 -0
- package/dist/src/crypto/scope.js +83 -0
- package/dist/src/crypto/ssh.d.ts +171 -0
- package/dist/src/crypto/ssh.js +396 -0
- package/dist/src/crypto/submission.d.ts +33 -0
- package/dist/src/crypto/submission.js +47 -0
- package/dist/src/crypto/trust-roots.d.ts +29 -0
- package/dist/src/crypto/trust-roots.js +39 -0
- package/dist/src/crypto/verify-consumed.d.ts +67 -0
- package/dist/src/crypto/verify-consumed.js +259 -0
- package/dist/src/crypto/verify-origin.d.ts +50 -0
- package/dist/src/crypto/verify-origin.js +151 -0
- package/dist/src/crypto/verify-publication.d.ts +60 -0
- package/dist/src/crypto/verify-publication.js +150 -0
- package/dist/src/defs.d.ts +24 -1
- package/dist/src/defs.js +145 -25
- package/dist/src/engine.d.ts +99 -3
- package/dist/src/engine.js +238 -34
- package/dist/src/factory.d.ts +16 -0
- package/dist/src/factory.js +16 -4
- package/dist/src/global-config.d.ts +59 -0
- package/dist/src/global-config.js +84 -0
- package/dist/src/hub.d.ts +75 -21
- package/dist/src/hub.js +123 -40
- package/dist/src/index.d.ts +17 -2
- package/dist/src/index.js +20 -2
- package/dist/src/install.d.ts +538 -0
- package/dist/src/install.js +1981 -0
- package/dist/src/lock.d.ts +15 -57
- package/dist/src/lock.js +251 -143
- package/dist/src/mcp/serve.d.ts +46 -22
- package/dist/src/mcp/serve.js +167 -44
- package/dist/src/mcp/server.js +12 -1
- package/dist/src/model.d.ts +15 -0
- package/dist/src/model.js +111 -1
- package/dist/src/order-resolver.d.ts +184 -0
- package/dist/src/order-resolver.js +252 -0
- package/dist/src/package-version.d.ts +10 -0
- package/dist/src/package-version.js +42 -0
- package/dist/src/paths.d.ts +14 -1
- package/dist/src/paths.js +18 -0
- package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
- package/dist/src/schemas/index.d.ts +1416 -0
- package/dist/src/schemas/index.js +31 -0
- package/dist/src/schemas/order.v1.schema.json +106 -0
- package/dist/src/schemas/origin.v1.schema.json +68 -0
- package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
- package/dist/src/schemas/publication.v1.schema.json +31 -0
- package/dist/src/schemas/revocation.v1.schema.json +39 -0
- package/dist/src/schemas/submission.v1.schema.json +61 -0
- package/dist/src/store/def-source.d.ts +52 -0
- package/dist/src/store/def-source.js +335 -0
- package/dist/src/store/index-file.d.ts +69 -0
- package/dist/src/store/index-file.js +151 -0
- package/dist/src/store/index.d.ts +27 -0
- package/dist/src/store/index.js +22 -0
- package/dist/src/store/ingestor.d.ts +43 -0
- package/dist/src/store/ingestor.js +211 -0
- package/dist/src/store/install.d.ts +228 -0
- package/dist/src/store/install.js +555 -0
- package/dist/src/store/instruction-source.d.ts +49 -0
- package/dist/src/store/instruction-source.js +298 -0
- package/dist/src/store/origin-evidence.d.ts +21 -0
- package/dist/src/store/origin-evidence.js +66 -0
- package/dist/src/store/pre-commit-verifier.d.ts +68 -0
- package/dist/src/store/pre-commit-verifier.js +418 -0
- package/dist/src/store/resolve.d.ts +138 -0
- package/dist/src/store/resolve.js +363 -0
- package/dist/src/store/types.d.ts +288 -0
- package/dist/src/store/types.js +356 -0
- package/dist/src/types.d.ts +45 -11
- package/dist/src/untar.d.ts +8 -23
- package/dist/src/untar.js +10 -136
- package/docs/agent-runner.md +86 -0
- package/docs/authoring.md +57 -6
- package/docs/bundles.md +250 -0
- package/docs/cli.md +1171 -97
- package/docs/crypto.md +816 -0
- package/docs/design.md +342 -20
- package/docs/embedding.md +132 -25
- package/docs/wire-contracts.md +380 -0
- package/package.json +6 -1
- package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
- package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
- package/plugins/claude-code/plugin/.mcp.json +14 -0
- package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
- package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
- package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
- package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
- package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
- package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
- package/plugins/codex/.agents/plugins/marketplace.json +21 -0
- package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
- package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
- package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
- package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
- package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
- package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
- package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
- package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
package/docs/crypto.md
ADDED
|
@@ -0,0 +1,816 @@
|
|
|
1
|
+
# Signing and key storage (WP-A2)
|
|
2
|
+
|
|
3
|
+
The engine's public crypto surface: **principal signing keys**, **SSHSIG
|
|
4
|
+
signing/verification**, and **DSSE envelopes**. Everything here is exported
|
|
5
|
+
from the package entry (`src/crypto/index.ts`), covered by the `test/crypto-*.test.ts`
|
|
6
|
+
suites, and interoperates with stock OpenSSH `ssh-keygen` on macOS and Linux CI.
|
|
7
|
+
|
|
8
|
+
## Why stock OpenSSH, not a JS signature library
|
|
9
|
+
|
|
10
|
+
Signatures are produced and verified by **stock `ssh-keygen -Y`** (`sign` and
|
|
11
|
+
`verify`), not by a JavaScript crypto library. Every invocation uses
|
|
12
|
+
`shell: false` with an argument vector, through an injected process seam. The
|
|
13
|
+
signer also uses stock `ssh-keygen -y` to derive the public half of a private
|
|
14
|
+
key, and the feature probe invokes a harmless `-Y` command through the same
|
|
15
|
+
seam. Callers depend on the format-neutral `Signer` interface rather than on
|
|
16
|
+
this OpenSSH implementation. Three reasons:
|
|
17
|
+
|
|
18
|
+
1. **Format neutrality for free.** SSHSIG's armored format, namespace binding,
|
|
19
|
+
and `allowed_signers` policy are implemented by OpenSSH itself; delegating
|
|
20
|
+
means the policy authority is the same binary every operator already trusts
|
|
21
|
+
for SSH. There is no custom authorization logic to keep in sync.
|
|
22
|
+
2. **Private material stays out of process interfaces.** The message rides on
|
|
23
|
+
child stdin, the private key is referenced only by a filesystem path in
|
|
24
|
+
`ssh-keygen` argv, and the armored signature is the only signing output
|
|
25
|
+
captured. Generated private bytes may exist transiently in the manager while
|
|
26
|
+
a record is written or a temporary signing file is materialized; the public
|
|
27
|
+
API never returns those bytes, and private bytes never appear in argv,
|
|
28
|
+
stdout, stderr, logs, thrown errors, or test snapshots.
|
|
29
|
+
3. **Portability cost is bounded and testable.** The requirement is one
|
|
30
|
+
binary — `ssh-keygen` with `-Y` support (OpenSSH 8.1+, present on macOS
|
|
31
|
+
and every mainstream Linux distro). When it is absent, crypto features fail
|
|
32
|
+
loudly instead of silently degrading; the test suites skip interop cases
|
|
33
|
+
with a named reason.
|
|
34
|
+
|
|
35
|
+
Private key bytes never appear in a repository, process arguments, stdout,
|
|
36
|
+
stderr, logs, thrown errors, or test snapshots. No public API returns a private
|
|
37
|
+
key; APIs return public descriptors or short-lived filesystem paths only.
|
|
38
|
+
|
|
39
|
+
The trade-off: every sign/verify spawns a child process (tens of
|
|
40
|
+
milliseconds). That is acceptable for the trust-surface call rates this layer
|
|
41
|
+
serves; a hot-path pure-JS signer can be added later behind the same `Signer`
|
|
42
|
+
interface without touching callers.
|
|
43
|
+
|
|
44
|
+
## The `Signer` interface
|
|
45
|
+
|
|
46
|
+
`Signer` is the format-neutral seam DSSE verification programs against:
|
|
47
|
+
|
|
48
|
+
- `sign(exactBytes: Buffer) → Promise<SignatureResult>` — sign the exact bytes
|
|
49
|
+
(a pre-auth encoding); returns `{ keyid, sig }`.
|
|
50
|
+
- `verify(bytes: Buffer, sig: Buffer) → Promise<VerifiedSignature | null>` —
|
|
51
|
+
`null` means "not this signer's signature" (a cryptographic miss), never an
|
|
52
|
+
exception. A hit returns `{ keyid, principal, format }`.
|
|
53
|
+
|
|
54
|
+
`SshSigner` (created via `createSshSigner({ namespace, signKeyPath, verify })`)
|
|
55
|
+
is the stock-OpenSSH implementation. `verify` has the shape
|
|
56
|
+
`{ principal, allowedSignersText }`; omit `signKeyPath` for verify-only use, or
|
|
57
|
+
omit `verify` for sign-only use. Its configuration (`SshSignerConfig`) and
|
|
58
|
+
process seam (`SshProcessAdapter`) are exported for hermetic tests; production
|
|
59
|
+
callers use the defaults. All errors are `SshSignerError` with fixed messages —
|
|
60
|
+
child stderr is never interpolated into error text.
|
|
61
|
+
|
|
62
|
+
## Key lifecycle and storage selection
|
|
63
|
+
|
|
64
|
+
`PrincipalKeyManager` owns one Ed25519 key per **principal key ref** —
|
|
65
|
+
`{ origin, kind, id }` where `kind` is one of the three local principals:
|
|
66
|
+
|
|
67
|
+
| kind | id |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `human` | the hub actor id (`whoami.actor.id`) |
|
|
70
|
+
| `machine` | the literal `"local"` |
|
|
71
|
+
| `agent` | the agent identity id |
|
|
72
|
+
|
|
73
|
+
`owenloop setup` step `[4/7] signing keys` ensures all three, in that order,
|
|
74
|
+
idempotently: a second run performs zero writes.
|
|
75
|
+
|
|
76
|
+
**One backend is selected once and never error-fallback.** A fallback after a
|
|
77
|
+
selected store fails could create two different private keys for the same
|
|
78
|
+
principal — a shadow identity. Selection:
|
|
79
|
+
|
|
80
|
+
1. **macOS:** `security` generic-password entries (service `owenloop-signing`,
|
|
81
|
+
account = SHA-256 of the canonical ref).
|
|
82
|
+
2. **Linux:** `secret-tool` (libsecret) when the executable is on `PATH`.
|
|
83
|
+
3. **Otherwise:** one atomic `0600` record file under
|
|
84
|
+
`$HOME/.owenloop/keys/<hash>.json`, with `$HOME/.owenloop` and `keys`
|
|
85
|
+
forced to `0700`; symlinked or non-directory paths are refused.
|
|
86
|
+
|
|
87
|
+
`OWENLOOP_NO_KEYCHAIN=1` forces the file backend on any platform — the same
|
|
88
|
+
explicit override the credential store honors. A `secret-tool lookup` exit
|
|
89
|
+
status of `1` means that the item is not found, not that libsecret failed; any
|
|
90
|
+
other nonzero lookup status is a backend failure. A failing selected backend
|
|
91
|
+
produces a fixed `signing-key storage (<backend>) failed: …` error and setup
|
|
92
|
+
stops. The manager does not error-fallback to another backend.
|
|
93
|
+
|
|
94
|
+
**Secrets never ride on argv or pipes.** Store writes pass the record on child
|
|
95
|
+
**stdin**; lookups redirect the secret-bearing stdout straight into a
|
|
96
|
+
pre-opened `0600` temp file descriptor. Nothing captures the secret into a
|
|
97
|
+
pipe, log, or error message.
|
|
98
|
+
|
|
99
|
+
`ensure(ref)` is serialized per ref by a file lock
|
|
100
|
+
(`$HOME/.owenloop/keys/<hash>.lock`): acquire → re-read → generate only when
|
|
101
|
+
still absent, so concurrent setups generate exactly once.
|
|
102
|
+
|
|
103
|
+
`inspect(ref)` returns only non-secret state, but validation of a generated
|
|
104
|
+
record is not a zero-byte operation: the manager temporarily writes the stored
|
|
105
|
+
private material to a `0600` file in a `0700` directory, runs stock
|
|
106
|
+
`ssh-keygen -y`, compares the derived public key and fingerprint, and removes
|
|
107
|
+
the directory in `finally`. The private text never appears in the inspection
|
|
108
|
+
result or in an exception.
|
|
109
|
+
|
|
110
|
+
### Materialization
|
|
111
|
+
|
|
112
|
+
`withSigningKey(ref, callback)` hands the callback a **path** to a usable
|
|
113
|
+
private key and nothing more: a generated key materializes as a `0600` file in
|
|
114
|
+
a unique `0700` temp dir and is removed in `finally`; a reused key passes only
|
|
115
|
+
its canonical path. No API returns private-key text.
|
|
116
|
+
|
|
117
|
+
### Publish-time signing
|
|
118
|
+
|
|
119
|
+
`owenloop publish` signs locally with the human principal key selected by the
|
|
120
|
+
project's bound hub origin. The signing chain is deliberately narrow:
|
|
121
|
+
|
|
122
|
+
1. `resolveRef(origin, 'human')` discovers the non-secret principal reference
|
|
123
|
+
from the local `<hash>.ref` pointer.
|
|
124
|
+
2. `inspect(ref)` read-only-confirms that setup already stored the key and
|
|
125
|
+
returns only its public descriptor, including the `publisherKeyId`
|
|
126
|
+
fingerprint. `publish` never calls `ensure`: publishing never creates or
|
|
127
|
+
repairs a signing key. During setup, an older key record created before ref
|
|
128
|
+
pointers existed is backfilled without changing the existing key.
|
|
129
|
+
3. `withSigningKey(ref, callback)` materializes the private key only for the
|
|
130
|
+
callback's controlled lifetime.
|
|
131
|
+
4. `createSshSigner({ namespace: DSSE_SSH_NAMESPACE, signKeyPath })` probes and
|
|
132
|
+
constructs the stock-OpenSSH signer.
|
|
133
|
+
5. `dsseSignPublication(payloadBytes, signer)` signs the canonical JSON bytes of
|
|
134
|
+
the publication record under `application/vnd.owenloop.publication.v1+json`.
|
|
135
|
+
6. When `--source` is present, `dsseSignOrigin(originPayloadBytes, signer)` signs
|
|
136
|
+
the canonical JSON bytes of a separate origin record under
|
|
137
|
+
`application/vnd.owenloop.origin.v1+json`, using the same signer object and
|
|
138
|
+
signing scope as the publication record.
|
|
139
|
+
|
|
140
|
+
Both records bind the 64-hex SHA-256 digest of the uncompressed canonical tar
|
|
141
|
+
returned by `packBundle`. The signer is constructed and the records are signed
|
|
142
|
+
before `publish` writes the `.wnlp` bundle or any sidecar. Signed output writes
|
|
143
|
+
the publication sidecar and, when `--source` is present, `<bundle>.origin.dsse`.
|
|
144
|
+
A publish without `--source` removes a stale origin sidecar; unsigned publish
|
|
145
|
+
also removes one because an unsigned origin would only be an unsigned label.
|
|
146
|
+
The hub is only a remote coordinator recorded by the project binding. The hub
|
|
147
|
+
stores or relays signed records but never signs, authors, derives, or defaults
|
|
148
|
+
origin data and cannot produce or complete either author signature.
|
|
149
|
+
|
|
150
|
+
The three origin source kinds are `git` (explicit repository identifier and
|
|
151
|
+
commit SHA), `console` (authoring user identity from a client-side signing
|
|
152
|
+
ceremony), and `agent` (agent identity and session). `attesterKeyId` is used only
|
|
153
|
+
to select verification candidates; verification cross-checks the hint against
|
|
154
|
+
the signer in the verified DSSE envelope.
|
|
155
|
+
|
|
156
|
+
### Submit-time signing
|
|
157
|
+
|
|
158
|
+
A remote driver can sign a `submit` at the driver boundary only when the driver
|
|
159
|
+
has the exact artifact version that the signature must name. The key reference
|
|
160
|
+
is `{ origin, kind: 'machine', id: 'local' }`. The driver reads the public
|
|
161
|
+
fingerprint with `inspect`, materializes the private key only inside
|
|
162
|
+
`withSigningKey`, builds the frozen `submission.v1` record, and signs its
|
|
163
|
+
canonical JSON payload with `dsseSignSubmission` under the
|
|
164
|
+
`owenloop-dsse-v1` namespace. The target `proof` request field is the serialized
|
|
165
|
+
DSSE envelope for that one submitted artifact path.
|
|
166
|
+
|
|
167
|
+
A judge approval may sign the existing judged version from the claim fingerprint.
|
|
168
|
+
A producer submit must not infer a new version from immutable `owes[].version`
|
|
169
|
+
or process-local state. The producer requires a retry-safe, hub-issued target
|
|
170
|
+
version; without one, the driver submits without a proof and warns once per
|
|
171
|
+
process. As of 2026-08-10, the production hub does not carry submit `proof`,
|
|
172
|
+
proof acceptance, authoritative producer-version allocation, or downstream
|
|
173
|
+
proof projection, so owenloop does not claim end-to-end production proof support.
|
|
174
|
+
|
|
175
|
+
The engine does not sign: local `Engine.green` is synchronous and commits inside
|
|
176
|
+
a synchronous store transaction. `owenloop green` remains deliberately unsigned
|
|
177
|
+
because local green does not cross a wire; moving the command to an asynchronous
|
|
178
|
+
signing path would add no trust coverage.
|
|
179
|
+
|
|
180
|
+
#### Canonical submission values
|
|
181
|
+
|
|
182
|
+
`canonicalValueBytes(value)` recursively sorts plain-object keys, preserves array
|
|
183
|
+
order, applies each object's `toJSON(key)` hook with the same key semantics as
|
|
184
|
+
`JSON.stringify`, and emits separator-tight UTF-8 JSON. `valueDigestHex(value)`
|
|
185
|
+
is the lowercase SHA-256 digest of those bytes. The canonical bytes make a
|
|
186
|
+
produced-value digest reproducible after the value crosses the JSON submit
|
|
187
|
+
transport; the driver signs the same canonical record representation that the
|
|
188
|
+
wire envelope carries.
|
|
189
|
+
|
|
190
|
+
Canonicalization fails loudly with `TypeError` when a value cannot be represented
|
|
191
|
+
faithfully. `Map`, `Set`, `RegExp`, class instances with fields, non-finite
|
|
192
|
+
numbers (`NaN`, `Infinity`, and `-Infinity`), `bigint`, and circular references
|
|
193
|
+
are rejected rather than silently becoming `{}` or another lossy value. A
|
|
194
|
+
submission record also rejects an empty `produced` list and negative or
|
|
195
|
+
non-integer artifact versions.
|
|
196
|
+
|
|
197
|
+
`buildSubmissionRecord` constructs the frozen `submission.v1` shape without
|
|
198
|
+
signing. `signSubmission` canonicalizes that record, signs the payload as a DSSE
|
|
199
|
+
submission envelope, and returns the serialized opaque proof sent with one
|
|
200
|
+
artifact submission.
|
|
201
|
+
|
|
202
|
+
## WP-D3 consume-side artifact verification
|
|
203
|
+
|
|
204
|
+
A consuming driver treats both the dynamic artifact values and the signed
|
|
205
|
+
submission records as untrusted transport data. The driver verifies a complete
|
|
206
|
+
order before the order reaches an agent prompt, an MCP model context, or a
|
|
207
|
+
command worker. The driver never removes only an offending path and continues
|
|
208
|
+
with the remaining packet; one failed link refuses the whole order.
|
|
209
|
+
|
|
210
|
+
For each entry in `order.consumes`, `verifyConsumed` applies this fixed order:
|
|
211
|
+
|
|
212
|
+
1. A missing proof is `absent`; no unsigned value is silently treated as
|
|
213
|
+
verified.
|
|
214
|
+
2. The driver parses the serialized envelope and verifies the DSSE signature
|
|
215
|
+
under `PAYLOAD_TYPE_SUBMISSION`.
|
|
216
|
+
3. Only after signature verification, the driver validates the decoded
|
|
217
|
+
`submission.v1` schema. The unsigned `producerKeyId` is used only to select a
|
|
218
|
+
local verification candidate; the authenticated signer key ID must equal the
|
|
219
|
+
signed record's `producerKeyId`.
|
|
220
|
+
4. The signed `produced[]` entry must cover the consumed artifact path. The
|
|
221
|
+
driver compares `valueDigestHex(deliveredValue)` with the signed
|
|
222
|
+
`valueDigest`, and compares the signed version with
|
|
223
|
+
`order.consumedFingerprint[path]` when that claim is present.
|
|
224
|
+
5. The authenticated producer key must chain through locally loaded enrollment
|
|
225
|
+
grants to the locally configured organization-root public key. Every grant
|
|
226
|
+
link is signature-checked, scope attenuation is enforced, and effective
|
|
227
|
+
revocations are applied.
|
|
228
|
+
6. When the consuming driver supplies a demand, the producer's effective scope
|
|
229
|
+
must satisfy that demand. A child grant can only narrow a parent grant; it
|
|
230
|
+
cannot widen pools, labels, namespaces, or delegation.
|
|
231
|
+
|
|
232
|
+
The same verification applies to an `owes[]` rejection thread when
|
|
233
|
+
`owes[].proof` is present. The proof is a `submission.v1` envelope whose one
|
|
234
|
+
`produced[]` entry names the owed artifact path and whose signed value digest
|
|
235
|
+
covers the complete `owes[].reasons` array. Verification therefore happens
|
|
236
|
+
before `REPLAY_TOKEN_BUDGET` truncates the thread for a resumed prompt.
|
|
237
|
+
|
|
238
|
+
The pure verifier returns four explicit verdicts:
|
|
239
|
+
|
|
240
|
+
| verdict | meaning |
|
|
241
|
+
| --- | --- |
|
|
242
|
+
| `verified` | DSSE, schema, path, value digest, version, enrollment chain, revocation, and any supplied-demand scope checks passed. |
|
|
243
|
+
| `absent` | No proof was supplied. |
|
|
244
|
+
| `unverifiable` | A required local prerequisite or verifier setup is unavailable. |
|
|
245
|
+
| `invalid` | Evidence was supplied but failed signature, schema, path, digest, version, chain, revocation, or scope validation. |
|
|
246
|
+
|
|
247
|
+
The consuming driver maps those verdicts according to `artifactPolicy`:
|
|
248
|
+
|
|
249
|
+
| verdict | `enforce` | `warn` | `off` |
|
|
250
|
+
| --- | --- | --- | --- |
|
|
251
|
+
| `verified` | admit | admit | admit |
|
|
252
|
+
| `absent` | refuse | warn and admit | admit |
|
|
253
|
+
| `unverifiable` | refuse | warn and admit | admit |
|
|
254
|
+
| `invalid` | refuse | refuse | refuse |
|
|
255
|
+
|
|
256
|
+
The `worker: command` rule is stronger than the table. Command workers refuse
|
|
257
|
+
`absent`, `unverifiable`, and `invalid` consumed evidence regardless of
|
|
258
|
+
`artifactPolicy`, including `off`. The consume-side gate runs before origin or
|
|
259
|
+
artifact policy lookup and before any command execution path can construct a
|
|
260
|
+
shell invocation. An unverified dynamic value must never reach `/bin/sh -c`.
|
|
261
|
+
Agent and MCP workers also fail closed when dynamic data exists but no
|
|
262
|
+
consume-side verifier is configured.
|
|
263
|
+
|
|
264
|
+
A refusal is an operator-facing integrity event, not an error to suppress or
|
|
265
|
+
work around. The refusal names the failed link and the artifact, using link
|
|
266
|
+
names such as `no-proof`, `signature`, `value-digest`, `version`, `chain`,
|
|
267
|
+
`scope`, or `prerequisite`, together with the workflow, run, and step. The gate
|
|
268
|
+
refuses the complete order; it never drops the offending path and serves a
|
|
269
|
+
partial packet.
|
|
270
|
+
|
|
271
|
+
**Decision A — version cross-check without fingerprint recomputation.** D3
|
|
272
|
+
checks each `consumedFingerprint[path]` version supplied by the consumer against
|
|
273
|
+
the signed `produced[].version`, but does not recompute the producer's complete
|
|
274
|
+
fingerprint map. The reduced packet does not include enough independently
|
|
275
|
+
authenticated upstream evidence to reconstruct every input version. A hostile
|
|
276
|
+
hub can therefore weaken a producer's declared lineage by supplying an explicit
|
|
277
|
+
empty or partial map. This is a named follow-up; the driver still verifies the
|
|
278
|
+
signed value and lineage evidence it does receive.
|
|
279
|
+
|
|
280
|
+
**Decision B — consumer-owned revocation anchor.** The consuming driver samples
|
|
281
|
+
its injected clock once per complete gate invocation and passes that instant as
|
|
282
|
+
`at`. Revocation is evaluated at that consumer-owned instant using
|
|
283
|
+
`effectiveFrom <= at`; the producer's signed timestamp is not a revocation
|
|
284
|
+
anchor. A key revocation that becomes effective after an earlier successful
|
|
285
|
+
consumption makes the same producer's artifact unconsumable on a later gate.
|
|
286
|
+
A producer timestamp ahead of the consumer clock is diagnostic only and does
|
|
287
|
+
not weaken revocation checks. Revocation cuts forward: a prior successful
|
|
288
|
+
decision is not rewritten, but a later consumption is checked against the cut.
|
|
289
|
+
|
|
290
|
+
**Scope enforcement status.** The pure verifier enforces `scopePermits` when a
|
|
291
|
+
caller supplies a pool, label, or namespace demand. The current production
|
|
292
|
+
`exec`, `agent-run`, and `hold` roles instantiate the verifier without a
|
|
293
|
+
demand, and `OrderPacket` carries no pool or label from which those roles could
|
|
294
|
+
derive one. Production gates therefore pass an empty demand: chain
|
|
295
|
+
termination, per-link signatures, attenuation-only-shrinks, and revocation are
|
|
296
|
+
enforced, but the demand-dependent scope-permission half of link 3 is currently
|
|
297
|
+
vacuous. Supplying a demand through the verifier seam enables that check. This
|
|
298
|
+
is a named follow-up, not a reason to bypass chain verification.
|
|
299
|
+
`packages/work/test/launch-gate-signer.test.ts` pins both halves of that
|
|
300
|
+
boundary: the chain and revocation cases run through the production command
|
|
301
|
+
driver, while the scope case calls the verifier directly with an explicit
|
|
302
|
+
demand and is named to say it is verifier-level, so wiring a demand into the
|
|
303
|
+
three roles later has a test to move.
|
|
304
|
+
|
|
305
|
+
### Adversarial coverage
|
|
306
|
+
|
|
307
|
+
`packages/work/test/launch-gate-*.test.ts` models the remote coordinator as a
|
|
308
|
+
fully attacker-controlled component and asserts the trust properties end to end
|
|
309
|
+
rather than per verifier. A fixture hub serves whatever bytes each scenario
|
|
310
|
+
tells it to and records them, and each scenario asserts three things: that the
|
|
311
|
+
tampered payload really was served, that the specific named refusal kind or
|
|
312
|
+
link fired, and that an untampered control run still reaches the executable
|
|
313
|
+
surface. The properties covered are that a hostile hub cannot alter an
|
|
314
|
+
executing instruction or shell command, cannot forge a consumed artifact value
|
|
315
|
+
or a judge rejection reason that reaches an agent prompt or a shell, and cannot
|
|
316
|
+
introduce a trusted signer; and that when it withholds, the driver stalls
|
|
317
|
+
without executing anything rather than degrading to unverified execution.
|
|
318
|
+
|
|
319
|
+
### Reusing an existing SSH key (human only)
|
|
320
|
+
|
|
321
|
+
`setup --reuse-ssh-key <path>` records the operator's own Ed25519 key for the
|
|
322
|
+
**human** principal instead of generating one. Before recording, the candidate
|
|
323
|
+
is validated with a non-secret sign/verify challenge against its own public
|
|
324
|
+
key (works for a private-key path, or a public-key path whose private half is
|
|
325
|
+
in ssh-agent). The record stores only the canonical `realpath` + public key + fingerprint —
|
|
326
|
+
the private bytes are never copied. For a private-key path, the public half is
|
|
327
|
+
derived with stock `ssh-keygen -y`; an adjacent `.pub` file is not trusted as
|
|
328
|
+
the identity source. Before every later signing callback, the manager resolves
|
|
329
|
+
the path again and checks that the current Ed25519 fingerprint still matches the
|
|
330
|
+
stored fingerprint.
|
|
331
|
+
|
|
332
|
+
Rules:
|
|
333
|
+
|
|
334
|
+
- **Human-only.** Machine and agent principals always get generated keys.
|
|
335
|
+
- **No rotation.** Passing `--reuse-ssh-key` when a human key already exists
|
|
336
|
+
is a hard conflict error; the existing key is kept.
|
|
337
|
+
- **Ed25519 only** in this work package.
|
|
338
|
+
|
|
339
|
+
## WP-D1 machine enrollment grants
|
|
340
|
+
|
|
341
|
+
WP-D1 registers a machine public key in a signed organization roster. The
|
|
342
|
+
machine key is not the grantor. The local human principal signs a frozen
|
|
343
|
+
`EnrollmentGrantRecord` whose `newKey` is the machine's public descriptor:
|
|
344
|
+
|
|
345
|
+
```ts
|
|
346
|
+
{
|
|
347
|
+
newKey: { keyid, keyType, openSshPublicKey, comment },
|
|
348
|
+
principal: { kind: 'machine', id: 'local' },
|
|
349
|
+
scope: {
|
|
350
|
+
pools: '*',
|
|
351
|
+
labels: '*',
|
|
352
|
+
namespaces: [],
|
|
353
|
+
delegation: { allowed: false },
|
|
354
|
+
},
|
|
355
|
+
grantedBy: '<human SHA256 fingerprint>',
|
|
356
|
+
validFrom: <milliseconds since Unix epoch>,
|
|
357
|
+
}
|
|
358
|
+
```
|
|
359
|
+
|
|
360
|
+
`buildEnrollmentGrant` performs no I/O and never reads a private key. The
|
|
361
|
+
builder copies and freezes the public descriptor, principal, scope arrays, and
|
|
362
|
+
delegation object. `DEFAULT_MACHINE_SCOPE` is the least-privilege D1 scope
|
|
363
|
+
shown above: unrestricted pool and label matching for the machine's own
|
|
364
|
+
operation, no namespace grants, and delegation denied. The frozen wire shape
|
|
365
|
+
is specified in [`docs/wire-contracts.md`](wire-contracts.md); WP-D1 does not
|
|
366
|
+
change that contract.
|
|
367
|
+
|
|
368
|
+
### Local roster verification
|
|
369
|
+
|
|
370
|
+
`verifyRosterEntry` verifies a relayed envelope in a fixed trust order:
|
|
371
|
+
|
|
372
|
+
1. Decode and validate the DSSE envelope and enrollment-grant payload.
|
|
373
|
+
2. Resolve the grantor key named by `grantedBy` from the local
|
|
374
|
+
`allowed_signers` trust root.
|
|
375
|
+
3. Verify the DSSE signature and cross-check the authenticated signer key ID
|
|
376
|
+
against `grantedBy`.
|
|
377
|
+
4. Call the optional `EnrollmentChainValidator` seam.
|
|
378
|
+
|
|
379
|
+
The public result is one of four explicit states:
|
|
380
|
+
|
|
381
|
+
| verdict | meaning |
|
|
382
|
+
|---|---|
|
|
383
|
+
| `enrolled` | payload, schema, signature, local signer authorization, and chain validation all succeeded; `keyid` is the enrolled machine fingerprint and `principal` is the authenticated signer principal |
|
|
384
|
+
| `unenrolled` | no envelope was supplied |
|
|
385
|
+
| `unverifiable` | a trust prerequisite is absent, including no local `allowed_signers` root or no installed chain validator |
|
|
386
|
+
| `invalid` | the envelope, payload, schema, signer authorization, signature, or chain-validator result failed |
|
|
387
|
+
|
|
388
|
+
The chain seam is deliberately narrow:
|
|
389
|
+
|
|
390
|
+
```ts
|
|
391
|
+
interface EnrollmentChainValidator {
|
|
392
|
+
validate(
|
|
393
|
+
grant: EnrollmentGrantRecord,
|
|
394
|
+
verifiedSignerKeyId: string,
|
|
395
|
+
): Promise<{ ok: true } | { ok: false; reason: string }>;
|
|
396
|
+
}
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
WP-D1 fails closed when `chainValidator` is absent. A valid signature proves
|
|
400
|
+
which key signed the grant; a signature does not prove that the signer chains
|
|
401
|
+
to the organization root. The WP-D4 chain validator supplies the organization
|
|
402
|
+
root, attenuation, and revocation checks when the local driver installs that
|
|
403
|
+
seam. D1 entries remain `unverifiable` until a host supplies that validator.
|
|
404
|
+
|
|
405
|
+
The hub receives and relays the signed envelope only. The hub never receives a
|
|
406
|
+
private key, creates a grant, signs a grant, or endorses a grant. Setup's
|
|
407
|
+
registration path signs with `PrincipalKeyManager.withSigningKey`, so private
|
|
408
|
+
bytes remain inside the local key-manager callback and only `{ envelope }` is
|
|
409
|
+
sent over HTTP.
|
|
410
|
+
|
|
411
|
+
## DSSE envelopes
|
|
412
|
+
|
|
413
|
+
Records that cross a trust boundary are wrapped in [DSSE](https://github.com/secure-systems-lab/dsse)
|
|
414
|
+
envelopes. The pre-auth encoding the signature covers:
|
|
415
|
+
|
|
416
|
+
```
|
|
417
|
+
DSSEv1 SP len(typeBytes) SP typeBytes SP len(payloadBytes) SP payloadBytes
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
`typeBytes` is the UTF-8 encoding of the payload type; `payloadBytes` is the
|
|
421
|
+
exact binary payload. Both lengths are ASCII decimal byte counts. Base64 on the
|
|
422
|
+
wire is decoded strictly — standard **and** URL-safe alphabets accepted,
|
|
423
|
+
malformed input rejected — because Node's built-in decoder is permissive.
|
|
424
|
+
SSHSIG signs and verifies this encoding under the namespace
|
|
425
|
+
`owenloop-dsse-v1` (`DSSE_SSH_NAMESPACE`).
|
|
426
|
+
|
|
427
|
+
Exactly six launch payload types are supported by the DSSE framing, and all six
|
|
428
|
+
are bound record classes in this package:
|
|
429
|
+
|
|
430
|
+
| constant | value |
|
|
431
|
+
|---|---|
|
|
432
|
+
| `PAYLOAD_TYPE_ENROLLMENT_GRANT` | `application/vnd.owenloop.enrollment-grant.v1+json` |
|
|
433
|
+
| `PAYLOAD_TYPE_REVOCATION` | `application/vnd.owenloop.revocation.v1+json` |
|
|
434
|
+
| `PAYLOAD_TYPE_SUBMISSION` | `application/vnd.owenloop.submission.v1+json` |
|
|
435
|
+
| `PAYLOAD_TYPE_POLICY_FLOOR` | `application/vnd.owenloop.policy-floor.v1+json` |
|
|
436
|
+
| `PAYLOAD_TYPE_ORIGIN` | `application/vnd.owenloop.origin.v1+json` |
|
|
437
|
+
| `PAYLOAD_TYPE_PUBLICATION` | `application/vnd.owenloop.publication.v1+json` |
|
|
438
|
+
|
|
439
|
+
`DSSE_RECORD_PAYLOAD_TYPES` is the frozen, exported runtime allow-list, and
|
|
440
|
+
`isDsseRecordPayloadType` is the exported guard. The generic
|
|
441
|
+
`dsseSignRecord` and `dsseVerifyRecord` wrappers apply that allow-list at
|
|
442
|
+
runtime: an arbitrary payload-type string, including an empty string or a
|
|
443
|
+
v2/attacker value, is rejected rather than accepted only by the TypeScript
|
|
444
|
+
union. The six fixed wrappers use their own constants; the publication wrapper
|
|
445
|
+
is `dsseSignPublication` / `dsseVerifyPublication`.
|
|
446
|
+
|
|
447
|
+
`dsseVerifyEnvelope` runs a fixed order — Base64 decode → PAE → signature
|
|
448
|
+
verification → payload-type check — and returns the payload bytes **exactly**.
|
|
449
|
+
A failed verification throws `DsseEnvelopeError`; a successful verification of
|
|
450
|
+
an empty payload returns a result with `payloadBytes.length === 0` and verified
|
|
451
|
+
signers, so the two outcomes are unambiguous. Malformed shapes also throw
|
|
452
|
+
`DsseEnvelopeError`. Duplicate signatures from the same trusted key count once;
|
|
453
|
+
a `threshold` option requires that many distinct signers.
|
|
454
|
+
|
|
455
|
+
## Wire record shapes
|
|
456
|
+
|
|
457
|
+
The record shapes that ride these DSSE envelopes are documented in
|
|
458
|
+
[`docs/wire-contracts.md`](wire-contracts.md). That document is the public
|
|
459
|
+
reference for the six bound record contracts, their schemas, and the versioning
|
|
460
|
+
rule.
|
|
461
|
+
|
|
462
|
+
## The role of `allowed_signers`
|
|
463
|
+
|
|
464
|
+
`parseAllowedSigners` parses the stock OpenSSH `allowed_signers` format
|
|
465
|
+
(principals, one comma-separated options field, key type, standard Base64 blob,
|
|
466
|
+
and trailing comment) **structurally**. The supported option syntax is
|
|
467
|
+
`cert-authority`, `namespaces="..."`, `valid-after="..."`, and
|
|
468
|
+
`valid-before="..."`; assignment values must use the stock quoted form.
|
|
469
|
+
`touch-required` is rejected because it is not a stock option supported by the
|
|
470
|
+
OpenSSH verifier used here. Repeated `cert-authority` options and empty option
|
|
471
|
+
slots between commas are retained as stock-tolerated syntax; a trailing comma
|
|
472
|
+
still produces a parse error. Quotes in a trailing comment are opaque after the
|
|
473
|
+
key blob and do not affect option parsing. The parser never throws: malformed
|
|
474
|
+
lines come back with their line numbers alongside the well-formed entries. It
|
|
475
|
+
deliberately does **not** implement OpenSSH pattern matching or authorization —
|
|
476
|
+
`ssh-keygen -Y verify` remains the policy authority, and accepted policy text is
|
|
477
|
+
fed back to it unchanged.
|
|
478
|
+
|
|
479
|
+
The Ed25519 rule applies to the key actually used for the operation, not to
|
|
480
|
+
every entry in the policy file. `SshSigner.sign` refuses a non-Ed25519 signing
|
|
481
|
+
key. During verification, OpenSSH may select an Ed25519, RSA, or ECDSA entry
|
|
482
|
+
from a mixed `allowed_signers` policy; `SshSigner` accepts the policy file but
|
|
483
|
+
refuses a successful verification when the key embedded in the verified
|
|
484
|
+
signature is not Ed25519. The policy file is not globally restricted to
|
|
485
|
+
Ed25519 entries.
|
|
486
|
+
|
|
487
|
+
### Known parser differences from stock OpenSSH
|
|
488
|
+
|
|
489
|
+
`parseAllowedSigners` is line-tolerant, but `SshSigner.verify` currently
|
|
490
|
+
rejects the **entire** policy file when any line produces a parse error (or when
|
|
491
|
+
no entries parse). Stock OpenSSH skips an unparseable line and continues with
|
|
492
|
+
other lines. This is a known pre-existing divergence, including realistic
|
|
493
|
+
`touch-required` and `verify-required` option lines; the line-tolerant parser
|
|
494
|
+
result must not be read as equivalent to successful `SshSigner` verification.
|
|
495
|
+
|
|
496
|
+
The structural parser also does not cross-check the declared key type against
|
|
497
|
+
the key type embedded in the Base64 public-key blob. Parsed `principals` retain
|
|
498
|
+
literal surrounding quotes where stock OpenSSH strips them. These fields are
|
|
499
|
+
structural output only; OpenSSH remains the authorization authority.
|
|
500
|
+
|
|
501
|
+
## Definition publication policy
|
|
502
|
+
|
|
503
|
+
The install path verifies the mutually exclusive publication sidecars written by
|
|
504
|
+
`publish`: `<bundle>.wnlp.dsse` or `<bundle>.wnlp.unsigned`. A signed publish may
|
|
505
|
+
also write the optional `<bundle>.origin.dsse` sidecar. The publication `.dsse`
|
|
506
|
+
sidecar is checked against the bundle digest and the local `allowed_signers`
|
|
507
|
+
trust root. Origin verification is separate: `verifyOrigin` returns `absent`
|
|
508
|
+
when the origin sidecar is missing, `verified` only after DSSE signature, schema,
|
|
509
|
+
signer-key, and bundle-digest checks pass, and `unverifiable` or `invalid` for
|
|
510
|
+
the corresponding failures. The trust-root path is
|
|
511
|
+
`$XDG_CONFIG_HOME/owenloop/allowed_signers` when
|
|
512
|
+
`XDG_CONFIG_HOME` is non-blank, or `$HOME/.config/owenloop/allowed_signers`
|
|
513
|
+
otherwise. A missing or malformed trust root produces the distinct
|
|
514
|
+
`unverifiable` verdict; a present signature that fails verification produces
|
|
515
|
+
`invalid`.
|
|
516
|
+
|
|
517
|
+
The execution and install policy is `defPolicy`, with built-in default `warn`.
|
|
518
|
+
Set `defPolicy` in the JSON settings file at
|
|
519
|
+
`$XDG_CONFIG_HOME/owenloop/settings.json` (or
|
|
520
|
+
`$HOME/.config/owenloop/settings.json`), for example:
|
|
521
|
+
|
|
522
|
+
```json
|
|
523
|
+
{
|
|
524
|
+
"defPolicy": "enforce"
|
|
525
|
+
}
|
|
526
|
+
```
|
|
527
|
+
|
|
528
|
+
`OWENLOOP_DEF_POLICY` overrides the settings file for a CLI invocation. The
|
|
529
|
+
precedence is explicit host-provided policy, then the environment, then the
|
|
530
|
+
settings file, then `warn`. An invalid policy value fails loudly rather than
|
|
531
|
+
weakening trust. The install-time and execution-time outcomes for `enforce`,
|
|
532
|
+
`warn`, and `off` are listed in [`docs/cli.md`](cli.md#definition-publication-policy).
|
|
533
|
+
|
|
534
|
+
`enforce` refuses unsigned and unverifiable definitions. `warn` warns and
|
|
535
|
+
permits those two verdicts for installation and agent work. `off` permits those
|
|
536
|
+
two verdicts silently for installation and agent work. `invalid` is refused at
|
|
537
|
+
every policy value. **Command workers always require `verified`; `off` never
|
|
538
|
+
relaxes that hard rule.** An execution resolver without a configured
|
|
539
|
+
publication verifier treats the definition as `unverifiable`, so command
|
|
540
|
+
workers refuse rather than assuming that integrity verification alone proves
|
|
541
|
+
publication trust.
|
|
542
|
+
|
|
543
|
+
The verifier does not write a verdict or sidecar into the immutable object
|
|
544
|
+
directory. The object remains governed by the bundle manifest integrity map.
|
|
545
|
+
|
|
546
|
+
## Definition origin policy
|
|
547
|
+
|
|
548
|
+
Publication trust and provenance trust are separate controls. A signed
|
|
549
|
+
publication may carry a second DSSE sidecar, `<bundle>.origin.dsse`, whose
|
|
550
|
+
payload identifies an origin source and binds the same bundle digest as the
|
|
551
|
+
publication record. A hub or other remote coordinator may relay that sidecar,
|
|
552
|
+
but never authors, derives, defaults, or verifies the origin rule. The install
|
|
553
|
+
path retains the exact verified sidecar bytes outside the immutable object at
|
|
554
|
+
`<store-root>/.owenloop/origins/<digest>.dsse`. Execution reads that retained
|
|
555
|
+
file and verifies it again against the current local `allowed_signers` trust
|
|
556
|
+
root; a later change to local trust material therefore takes effect at the
|
|
557
|
+
execution boundary. Only a `verified` origin verdict is retained. A bundle
|
|
558
|
+
carrying only `<bundle>.origin.dsse` — with neither a publication `.dsse` nor an
|
|
559
|
+
unsigned marker — is refused at install for every origin-policy value, including
|
|
560
|
+
`off`. `publish` never emits that shape; `--unsigned` removes both sidecars.
|
|
561
|
+
|
|
562
|
+
Origin verification has four distinct verdicts:
|
|
563
|
+
|
|
564
|
+
- `verified` — the origin DSSE signature, schema, signer key, and bundle digest
|
|
565
|
+
all verify.
|
|
566
|
+
- `absent` — no origin bytes are available. For a signed file publication, this
|
|
567
|
+
means no sidecar was recorded. An unsigned publication or a non-file install
|
|
568
|
+
source also produces `absent`, but those definitions structurally cannot carry
|
|
569
|
+
an origin; those cases must not be described as “no origin was recorded.”
|
|
570
|
+
- `unverifiable` — a prerequisite such as the local trust root or verifier is
|
|
571
|
+
unavailable or unusable.
|
|
572
|
+
- `invalid` — a present origin sidecar fails its signature, schema, signer, or
|
|
573
|
+
digest checks. Invalid evidence is an attack signal and refuses at every
|
|
574
|
+
policy mode, including `off`.
|
|
575
|
+
|
|
576
|
+
`originRules` is an optional settings-file object mapping namespace patterns to
|
|
577
|
+
minimum origin strengths. Namespace matching has a deliberately small grammar:
|
|
578
|
+
`prod` is an exact namespace rule; `prod*` is a namespace-prefix rule; and a
|
|
579
|
+
trailing `/*` is accepted as sugar, so `prod/*` means the exact namespace
|
|
580
|
+
`prod`. `*` and `*/*` are catch-all rules. Interior wildcards, repeated
|
|
581
|
+
wildcards, `?`, `[`, empty keys, control characters, and other slash forms are
|
|
582
|
+
named settings errors. Exact rules beat every prefix rule; among prefixes, the
|
|
583
|
+
longest matching prefix wins. Keys that normalize to equal specificity, such
|
|
584
|
+
as `prod` and `prod/*`, are a named duplicate error rather than an arbitrary
|
|
585
|
+
winner.
|
|
586
|
+
|
|
587
|
+
The rule value is a minimum, not a set-membership label. Origin strength is
|
|
588
|
+
ordered `git` > `console` > `agent`: a `console` rule admits verified `git` and
|
|
589
|
+
`console` origins, while an `agent` rule admits all three. `any` imposes no
|
|
590
|
+
origin requirement, so `absent` and `unverifiable` pass that rule; a namespace
|
|
591
|
+
with no matching rule has no origin requirement. A verified origin is the only
|
|
592
|
+
verdict with a strength rank. `absent` and `unverifiable` fail a non-`any` rule
|
|
593
|
+
with distinct diagnostics. No rule may make invalid evidence acceptable.
|
|
594
|
+
Even with an empty `originRules` map, the default execution resolver invokes
|
|
595
|
+
its origin verifier once per order; the expensive index reverse-scan is skipped,
|
|
596
|
+
but invalid retained origin evidence still refuses.
|
|
597
|
+
|
|
598
|
+
The local origin mode uses the same vocabulary as `defPolicy`:
|
|
599
|
+
`enforce | warn | off`. These are policy values, not trust modes. `Seamless`,
|
|
600
|
+
`Strict`, and `Paranoid` are the separate trust-mode axis; `Seamless` maps to
|
|
601
|
+
`warn` and `Strict` maps to `enforce`. `off` is a local operator escape hatch,
|
|
602
|
+
not a trust mode. `originPolicy` follows explicit host option, then
|
|
603
|
+
`OWENLOOP_ORIGIN_POLICY`, then the settings-file value, then the built-in
|
|
604
|
+
`warn` default. The `originRules` map follows explicit host option, then the
|
|
605
|
+
settings-file value, then an empty map; there is intentionally no environment
|
|
606
|
+
variable spelling for the map. Origin mode remains parallel to publication
|
|
607
|
+
mode; an origin requirement never raises or lowers `defPolicy`.
|
|
608
|
+
|
|
609
|
+
A verified organization policy floor supplies the parallel minimum:
|
|
610
|
+
`originRules: advisory` maps to local `originPolicy: warn`, and
|
|
611
|
+
`originRules: enforced` maps to `originPolicy: enforce`. The floor is merged
|
|
612
|
+
monotonically after local precedence, so a local `off` cannot opt out of an
|
|
613
|
+
enforced origin floor. The `unsignedArtifacts` axis similarly maps `warn` to
|
|
614
|
+
`artifactPolicy: warn` and `refuse` to `artifactPolicy: enforce`. Both axes are
|
|
615
|
+
wired at the driver boundaries; the remaining unenforced floor gap is
|
|
616
|
+
`trustMode`.
|
|
617
|
+
|
|
618
|
+
The command-worker hard rule remains independent of origin policy. A
|
|
619
|
+
`worker: command` order must pass the publication verification gate before any
|
|
620
|
+
origin-policy lookup, and must then satisfy the origin check. Unsigned,
|
|
621
|
+
unverifiable, or invalid publication evidence never reaches the shell;
|
|
622
|
+
`originPolicy: off` and every policy-floor preset leave that publication gate
|
|
623
|
+
unchanged.
|
|
624
|
+
|
|
625
|
+
## Enrollment chains, attenuation, and revocation
|
|
626
|
+
|
|
627
|
+
Enrollment trust is separate from publication-signature trust. A key is trusted
|
|
628
|
+
if and only if its enrollment chain terminates at the supplied local
|
|
629
|
+
organization-root anchor. A hub or other remote coordinator may relay signed
|
|
630
|
+
envelopes, but a remote assertion cannot make a key trusted.
|
|
631
|
+
|
|
632
|
+
`validateEnrollmentChain` is the pure validator. Its input contains the target
|
|
633
|
+
key ID, the org-root public-key text, signed grant envelopes, optional signed
|
|
634
|
+
revocation envelopes, and an explicit validation instant `at` in epoch
|
|
635
|
+
milliseconds. Every grant link is verified separately with a signer whose
|
|
636
|
+
`allowed_signers` text contains exactly that link's parent key. A roster entry
|
|
637
|
+
without a grant, a cycle, an ambiguous duplicate grant, or a chain that stops
|
|
638
|
+
before the anchor is `invalid`; the validator never picks a convenient chain.
|
|
639
|
+
A grant is also checked for its `validFrom` time and for the Ed25519 key type.
|
|
640
|
+
|
|
641
|
+
The org root is an injected local anchor, not a wire field. Neither an
|
|
642
|
+
`EnrollmentGrantRecord` nor a `RevocationRecord` contains an `org` field, and
|
|
643
|
+
the root has no grant record. The walk terminates when the current key ID
|
|
644
|
+
matches the key ID derived from the supplied anchor; that absence of a grant is
|
|
645
|
+
what makes the key the root. Asking to validate the root itself succeeds at
|
|
646
|
+
depth zero with `ORG_ROOT_SCOPE`.
|
|
647
|
+
|
|
648
|
+
The result has three states:
|
|
649
|
+
|
|
650
|
+
| verdict | meaning |
|
|
651
|
+
|---|---|
|
|
652
|
+
| `verified` | the chain reaches the local anchor, every link verifies, and all scope and revocation checks pass |
|
|
653
|
+
| `unverifiable` | a local prerequisite cannot be used, such as a missing or malformed anchor or unusable `ssh-keygen` |
|
|
654
|
+
| `invalid` | the supplied roster or revocation set is well-formed but does not establish the requested trust |
|
|
655
|
+
|
|
656
|
+
There is no `unsigned` chain verdict. An absent grant for a non-root target is
|
|
657
|
+
an invalid chain, not an unsigned one. `validateProducer` runs the same chain
|
|
658
|
+
validation and then checks a requested `{ pool?, label?, namespace? }` demand
|
|
659
|
+
against the target's effective scope.
|
|
660
|
+
|
|
661
|
+
### Scope attenuation
|
|
662
|
+
|
|
663
|
+
A child grant may be narrower than its parent's effective grant, never wider.
|
|
664
|
+
For each of `pools`, `labels`, and `namespaces`, the containment rule is:
|
|
665
|
+
|
|
666
|
+
| parent | child | result |
|
|
667
|
+
|---|---|---|
|
|
668
|
+
| `"*"` | any array or `"*"` | permitted |
|
|
669
|
+
| string array | `"*"` | rejected as widening |
|
|
670
|
+
| string array | string array | permitted only when every child value is in the parent array |
|
|
671
|
+
|
|
672
|
+
An empty array is distinct from `"*"`: an empty array permits no values. The
|
|
673
|
+
delegation limit attenuates separately. A parent with delegation disabled cannot
|
|
674
|
+
sign a grant; an unbounded parent may delegate any child scope; a numeric parent
|
|
675
|
+
with `maxDepth: N` may sign a non-delegating child or a child with numeric
|
|
676
|
+
`maxDepth: M` where `M <= N - 1`. A numeric parent never permits an unbounded
|
|
677
|
+
child. The org root starts with `ORG_ROOT_SCOPE`: all three axes are `"*"` and
|
|
678
|
+
delegation is unbounded.
|
|
679
|
+
|
|
680
|
+
### Revocation
|
|
681
|
+
|
|
682
|
+
Validation applies signed revocations at the explicit `at` instant. A verified
|
|
683
|
+
revocation whose `effectiveFrom <= at` kills the named key, and a chain with a
|
|
684
|
+
dead link is invalid. Because descendants must walk through their ancestors,
|
|
685
|
+
revocation cascades forward transitively without a separate descendant pass.
|
|
686
|
+
A grant or artifact evaluated at an earlier `at` remains valid before the cut;
|
|
687
|
+
revocation is forward-only.
|
|
688
|
+
|
|
689
|
+
The revocation signer must be the org root or an ancestor of the revoked key
|
|
690
|
+
whose delegation scope allows delegation. A backdated revocation
|
|
691
|
+
(`effectiveFrom < issuedAt`) is org-root-only and is reported through the
|
|
692
|
+
validator's injected backdated-revocation sink. The `backdated` field must agree
|
|
693
|
+
with the timestamp comparison before signer authority is considered. A
|
|
694
|
+
revocation of the org root itself is invalid rather than silently disabling the
|
|
695
|
+
whole organization.
|
|
696
|
+
|
|
697
|
+
### Local anchor and envelope files
|
|
698
|
+
|
|
699
|
+
The optional filesystem loader derives paths from injected environment state:
|
|
700
|
+
`XDG_CONFIG_HOME` wins over `HOME`; there is no ambient home-directory lookup.
|
|
701
|
+
The local layout is:
|
|
702
|
+
|
|
703
|
+
```text
|
|
704
|
+
<config>/owenloop/org-root.pub # public anchor, 0644
|
|
705
|
+
<config>/owenloop/org-root # private anchor, 0600
|
|
706
|
+
<config>/owenloop/roster/<sha256hex(keyid)>.grant.dsse
|
|
707
|
+
<config>/owenloop/revocations/<sha256hex(keyid)>.revocation.dsse
|
|
708
|
+
```
|
|
709
|
+
|
|
710
|
+
The root key is stored outside `PrincipalKeyManager` because the root is not a
|
|
711
|
+
hub-scoped principal key. The containing directory is `0700`; the private root
|
|
712
|
+
is never returned by the library or placed in an envelope. `loadRoster` and
|
|
713
|
+
`loadRevocations` return raw envelope bytes to the pure validator and refuse
|
|
714
|
+
symlinked or non-regular files.
|
|
715
|
+
|
|
716
|
+
## Admin-signed policy floors
|
|
717
|
+
|
|
718
|
+
A policy floor is an org-wide minimum for local enforcement. An org admin signs
|
|
719
|
+
one DSSE record with payload type
|
|
720
|
+
`application/vnd.owenloop.policy-floor.v1+json`. A driver verifies the exact
|
|
721
|
+
record against local trust material before using the record:
|
|
722
|
+
|
|
723
|
+
1. The DSSE envelope and policy-floor schema must verify.
|
|
724
|
+
2. The authenticated signer key must be present in the local enrollment
|
|
725
|
+
material, and the signer's enrollment chain must terminate at the local
|
|
726
|
+
organization-root anchor. Revocations are evaluated at the supplied
|
|
727
|
+
validation instant.
|
|
728
|
+
3. The signer's effective scope must be unrestricted on all three axes:
|
|
729
|
+
`pools`, `labels`, and `namespaces` must each be `"*"`. Under scope
|
|
730
|
+
attenuation, that is genuine organization-wide admin scope; a narrower key
|
|
731
|
+
cannot sign an organization-wide floor.
|
|
732
|
+
|
|
733
|
+
A hub or other remote coordinator relays the signed record but never authors,
|
|
734
|
+
derives, weakens, or signs the floor. The relaying transport is not a trust
|
|
735
|
+
anchor.
|
|
736
|
+
|
|
737
|
+
### Monotone merge with local policy
|
|
738
|
+
|
|
739
|
+
A verified floor can only raise local strictness, never lower it. The driver
|
|
740
|
+
maps the floor's `unsignedDefs` axis into the existing `defPolicy` vocabulary:
|
|
741
|
+
|
|
742
|
+
| floor `unsignedDefs` | minimum local `defPolicy` |
|
|
743
|
+
|---|---|
|
|
744
|
+
| `warn` | `warn` |
|
|
745
|
+
| `refuse` | `enforce` |
|
|
746
|
+
|
|
747
|
+
The effective policy is the stricter of local policy and the floor minimum:
|
|
748
|
+
`off < warn < enforce`. The floor vocabulary has no value that maps to `off`,
|
|
749
|
+
so a floor is structurally unable to lower policy. In particular, local `off`
|
|
750
|
+
plus a verified floor produces at least `warn`; the local operator cannot opt
|
|
751
|
+
out of that org floor.
|
|
752
|
+
|
|
753
|
+
### Failure behavior and current limits
|
|
754
|
+
|
|
755
|
+
Absence is never permission. A missing or failed floor supplies no floor to the
|
|
756
|
+
merge, so the driver's local policy remains exactly unchanged. For a delivered
|
|
757
|
+
envelope, verification reports `invalid` or `unverifiable` instead of throwing
|
|
758
|
+
for every failure path:
|
|
759
|
+
|
|
760
|
+
| situation | result |
|
|
761
|
+
|---|---|
|
|
762
|
+
| no floor delivered | local policy unchanged; no floor is merged |
|
|
763
|
+
| malformed envelope or payload, including wrong payload type or schema failure | `invalid`; local policy unchanged |
|
|
764
|
+
| unsigned floor or signature that does not verify | `invalid`; local policy unchanged |
|
|
765
|
+
| signer chain does not terminate at the local org root | `invalid`; local policy unchanged |
|
|
766
|
+
| signer lacks unrestricted admin scope | `invalid`; local policy unchanged |
|
|
767
|
+
| signer key is revoked at the validation instant | `invalid`; local policy unchanged |
|
|
768
|
+
| local org-root anchor or other verification prerequisite is unavailable | `unverifiable`; local policy unchanged |
|
|
769
|
+
|
|
770
|
+
The frozen floor has four axes. This package enforces three of them:
|
|
771
|
+
`unsignedDefs` through `defPolicy`, `unsignedArtifacts` through the parallel
|
|
772
|
+
`artifactPolicy`, and `originRules` through the parallel `originPolicy`:
|
|
773
|
+
|
|
774
|
+
| axis | current state |
|
|
775
|
+
|---|---|
|
|
776
|
+
| `unsignedDefs` | mapped into `defPolicy` and enforced |
|
|
777
|
+
| `trustMode` | accepted and carried, but not evaluated |
|
|
778
|
+
| `unsignedArtifacts` | mapped into `artifactPolicy` and enforced at consume-side driver boundaries |
|
|
779
|
+
| `originRules` | mapped into `originPolicy` and enforced |
|
|
780
|
+
|
|
781
|
+
The merge result names the remaining unenforced `trustMode` axis in `gaps`
|
|
782
|
+
rather than silently dropping it. Installation and execution apply the
|
|
783
|
+
origin-policy and artifact-policy results; callers do not currently surface the
|
|
784
|
+
`trustMode` gap. The `policyFloor` option remains an injection seam: the floor
|
|
785
|
+
has effect only when a host loads and verifies a signed floor and passes the
|
|
786
|
+
verified record through that seam.
|
|
787
|
+
|
|
788
|
+
L0, L1, and L2 are documented bundles of concrete floor values, not alternate
|
|
789
|
+
policy primitives:
|
|
790
|
+
|
|
791
|
+
| preset | `trustMode` | `unsignedDefs` | `unsignedArtifacts` | `originRules` |
|
|
792
|
+
|---|---|---|---|---|
|
|
793
|
+
| L0 | `seamless` | `warn` | `warn` | `advisory` |
|
|
794
|
+
| L1 | `seamless` | `refuse` | `refuse` | `advisory` |
|
|
795
|
+
| L2 | `strict` | `refuse` | `refuse` | `enforced` |
|
|
796
|
+
|
|
797
|
+
The `trustMode` preset value is still only carried and reported as a gap in
|
|
798
|
+
this package. The `unsignedArtifacts` value maps to the parallel
|
|
799
|
+
consume-side artifact-policy minimum described above, and `originRules` maps to
|
|
800
|
+
the parallel origin-policy minimum.
|
|
801
|
+
|
|
802
|
+
**Command-worker hard rule.** A `worker: command` order still requires full
|
|
803
|
+
enforcement: a verified definition, a verified enrollment chain, and a
|
|
804
|
+
scope-checked signer. The gate runs before the floor-derived policy value is
|
|
805
|
+
read and fails closed regardless of local policy, including `off`, and
|
|
806
|
+
regardless of any floor. A floor cannot relax this rule.
|
|
807
|
+
|
|
808
|
+
## Out of scope (future work)
|
|
809
|
+
|
|
810
|
+
Publish-time author-side DSSE signing is implemented by `owenloop publish`.
|
|
811
|
+
Transport relay and the following extensions remain out of scope:
|
|
812
|
+
|
|
813
|
+
- Key **rotation** wiring for stored principal keys.
|
|
814
|
+
- Certificate (`cert-authority`) chains and hardware-backed signing flows.
|
|
815
|
+
- A pure-JS signer for hot paths (the `Signer` seam is already in place).
|
|
816
|
+
- Threshold schemes beyond "N distinct trusted keys".
|