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.
Files changed (211) hide show
  1. package/CHANGELOG.md +45 -0
  2. package/README.md +137 -35
  3. package/bin/owenloop.mjs +49 -1
  4. package/dist/packages/work/src/agent/brief.d.ts +8 -4
  5. package/dist/packages/work/src/agent/brief.js +7 -3
  6. package/dist/packages/work/src/agent/loop.d.ts +13 -7
  7. package/dist/packages/work/src/agent/loop.js +136 -9
  8. package/dist/packages/work/src/agent/model-policy.d.ts +49 -0
  9. package/dist/packages/work/src/agent/model-policy.js +138 -0
  10. package/dist/packages/work/src/bundle/cache.d.ts +7 -5
  11. package/dist/packages/work/src/bundle/cache.js +20 -6
  12. package/dist/packages/work/src/bundle/fetch.d.ts +7 -5
  13. package/dist/packages/work/src/bundle/fetch.js +27 -7
  14. package/dist/packages/work/src/bundle/types.d.ts +8 -4
  15. package/dist/packages/work/src/consumed-verifier.d.ts +45 -0
  16. package/dist/packages/work/src/consumed-verifier.js +205 -0
  17. package/dist/packages/work/src/exec/instructions.d.ts +99 -0
  18. package/dist/packages/work/src/exec/instructions.js +323 -0
  19. package/dist/packages/work/src/exec/loop.d.ts +12 -1
  20. package/dist/packages/work/src/exec/loop.js +137 -20
  21. package/dist/packages/work/src/exec/payload.d.ts +29 -0
  22. package/dist/packages/work/src/exec/payload.js +54 -0
  23. package/dist/packages/work/src/exec/receipt.d.ts +9 -6
  24. package/dist/packages/work/src/exec/receipt.js +12 -1
  25. package/dist/packages/work/src/exec/runner.d.ts +7 -1
  26. package/dist/packages/work/src/exec/runner.js +74 -3
  27. package/dist/packages/work/src/harness/child-env.js +7 -0
  28. package/dist/packages/work/src/harness/claude.d.ts +20 -8
  29. package/dist/packages/work/src/harness/claude.js +260 -58
  30. package/dist/packages/work/src/harness/codex.d.ts +5 -4
  31. package/dist/packages/work/src/harness/codex.js +169 -41
  32. package/dist/packages/work/src/harness/contract.d.ts +36 -11
  33. package/dist/packages/work/src/harness/fake.js +1 -0
  34. package/dist/packages/work/src/harness/jsonrpc-stdio.js +7 -0
  35. package/dist/packages/work/src/harness/permissions.d.ts +16 -3
  36. package/dist/packages/work/src/harness/permissions.js +102 -13
  37. package/dist/packages/work/src/harness/session-store.d.ts +27 -9
  38. package/dist/packages/work/src/harness/session-store.js +271 -67
  39. package/dist/packages/work/src/hold/mcp.d.ts +25 -5
  40. package/dist/packages/work/src/hold/mcp.js +126 -11
  41. package/dist/packages/work/src/hub/client.d.ts +2 -1
  42. package/dist/packages/work/src/hub/client.js +14 -1
  43. package/dist/packages/work/src/hub/types.d.ts +69 -33
  44. package/dist/packages/work/src/hub/types.js +8 -10
  45. package/dist/packages/work/src/mcp/server.js +1 -1
  46. package/dist/packages/work/src/owenloop-bin.d.ts +1 -0
  47. package/dist/packages/work/src/owenloop-bin.js +18 -0
  48. package/dist/packages/work/src/roles/agent-run.d.ts +12 -6
  49. package/dist/packages/work/src/roles/agent-run.js +116 -34
  50. package/dist/packages/work/src/roles/exec.d.ts +8 -0
  51. package/dist/packages/work/src/roles/exec.js +27 -2
  52. package/dist/packages/work/src/roles/hold.d.ts +4 -0
  53. package/dist/packages/work/src/roles/hold.js +44 -5
  54. package/dist/packages/work/src/roles/lint.d.ts +3 -4
  55. package/dist/packages/work/src/roles/lint.js +41 -7
  56. package/dist/packages/work/src/roles/settings.js +5 -0
  57. package/dist/packages/work/src/roles/shift.d.ts +1 -0
  58. package/dist/packages/work/src/roles/shift.js +23 -1
  59. package/dist/packages/work/src/settings/settings.d.ts +17 -1
  60. package/dist/packages/work/src/settings/settings.js +39 -0
  61. package/dist/packages/work/src/shift/loop.d.ts +14 -3
  62. package/dist/packages/work/src/shift/loop.js +447 -164
  63. package/dist/packages/work/src/shift/protocol.d.ts +4 -0
  64. package/dist/packages/work/src/shift/runtime.d.ts +2 -0
  65. package/dist/packages/work/src/shift/runtime.js +66 -3
  66. package/dist/packages/work/src/shift/spawn.d.ts +41 -18
  67. package/dist/packages/work/src/shift/spawn.js +89 -31
  68. package/dist/packages/work/src/shift/state.d.ts +53 -51
  69. package/dist/packages/work/src/shift/state.js +325 -102
  70. package/dist/packages/work/src/submit-proof.d.ts +36 -0
  71. package/dist/packages/work/src/submit-proof.js +93 -0
  72. package/dist/src/add.d.ts +64 -259
  73. package/dist/src/add.js +81 -615
  74. package/dist/src/archive.d.ts +97 -0
  75. package/dist/src/archive.js +591 -0
  76. package/dist/src/bundle/index.d.ts +64 -0
  77. package/dist/src/bundle/index.js +508 -0
  78. package/dist/src/bundle/manifest.d.ts +50 -0
  79. package/dist/src/bundle/manifest.js +435 -0
  80. package/dist/src/bundle/runtime.d.ts +26 -0
  81. package/dist/src/bundle/runtime.js +64 -0
  82. package/dist/src/bundle/tar.d.ts +62 -0
  83. package/dist/src/bundle/tar.js +238 -0
  84. package/dist/src/bundle/types.d.ts +105 -0
  85. package/dist/src/bundle/types.js +21 -0
  86. package/dist/src/cli.d.ts +90 -20
  87. package/dist/src/cli.js +2407 -365
  88. package/dist/src/credentials.d.ts +4 -3
  89. package/dist/src/credentials.js +21 -19
  90. package/dist/src/crypto/allowed-signers.d.ts +68 -0
  91. package/dist/src/crypto/allowed-signers.js +307 -0
  92. package/dist/src/crypto/canonical.d.ts +8 -0
  93. package/dist/src/crypto/canonical.js +92 -0
  94. package/dist/src/crypto/chain.d.ts +65 -0
  95. package/dist/src/crypto/chain.js +377 -0
  96. package/dist/src/crypto/dsse.d.ts +209 -0
  97. package/dist/src/crypto/dsse.js +282 -0
  98. package/dist/src/crypto/enrollment.d.ts +78 -0
  99. package/dist/src/crypto/enrollment.js +186 -0
  100. package/dist/src/crypto/index.d.ts +48 -0
  101. package/dist/src/crypto/index.js +44 -0
  102. package/dist/src/crypto/keys.d.ts +258 -0
  103. package/dist/src/crypto/keys.js +908 -0
  104. package/dist/src/crypto/org-root.d.ts +33 -0
  105. package/dist/src/crypto/org-root.js +78 -0
  106. package/dist/src/crypto/origin-rules.d.ts +56 -0
  107. package/dist/src/crypto/origin-rules.js +143 -0
  108. package/dist/src/crypto/policy-floor.d.ts +98 -0
  109. package/dist/src/crypto/policy-floor.js +353 -0
  110. package/dist/src/crypto/records.d.ts +316 -0
  111. package/dist/src/crypto/records.js +157 -0
  112. package/dist/src/crypto/scope.d.ts +49 -0
  113. package/dist/src/crypto/scope.js +83 -0
  114. package/dist/src/crypto/ssh.d.ts +171 -0
  115. package/dist/src/crypto/ssh.js +396 -0
  116. package/dist/src/crypto/submission.d.ts +33 -0
  117. package/dist/src/crypto/submission.js +47 -0
  118. package/dist/src/crypto/trust-roots.d.ts +29 -0
  119. package/dist/src/crypto/trust-roots.js +39 -0
  120. package/dist/src/crypto/verify-consumed.d.ts +67 -0
  121. package/dist/src/crypto/verify-consumed.js +259 -0
  122. package/dist/src/crypto/verify-origin.d.ts +50 -0
  123. package/dist/src/crypto/verify-origin.js +151 -0
  124. package/dist/src/crypto/verify-publication.d.ts +60 -0
  125. package/dist/src/crypto/verify-publication.js +150 -0
  126. package/dist/src/defs.d.ts +24 -1
  127. package/dist/src/defs.js +145 -25
  128. package/dist/src/engine.d.ts +99 -3
  129. package/dist/src/engine.js +238 -34
  130. package/dist/src/factory.d.ts +16 -0
  131. package/dist/src/factory.js +16 -4
  132. package/dist/src/global-config.d.ts +59 -0
  133. package/dist/src/global-config.js +84 -0
  134. package/dist/src/hub.d.ts +75 -21
  135. package/dist/src/hub.js +123 -40
  136. package/dist/src/index.d.ts +17 -2
  137. package/dist/src/index.js +20 -2
  138. package/dist/src/install.d.ts +538 -0
  139. package/dist/src/install.js +1981 -0
  140. package/dist/src/lock.d.ts +15 -57
  141. package/dist/src/lock.js +251 -143
  142. package/dist/src/mcp/serve.d.ts +46 -22
  143. package/dist/src/mcp/serve.js +167 -44
  144. package/dist/src/mcp/server.js +12 -1
  145. package/dist/src/model.d.ts +15 -0
  146. package/dist/src/model.js +111 -1
  147. package/dist/src/order-resolver.d.ts +184 -0
  148. package/dist/src/order-resolver.js +252 -0
  149. package/dist/src/package-version.d.ts +10 -0
  150. package/dist/src/package-version.js +42 -0
  151. package/dist/src/paths.d.ts +14 -1
  152. package/dist/src/paths.js +18 -0
  153. package/dist/src/schemas/enrollment-grant.v1.schema.json +90 -0
  154. package/dist/src/schemas/index.d.ts +1416 -0
  155. package/dist/src/schemas/index.js +31 -0
  156. package/dist/src/schemas/order.v1.schema.json +106 -0
  157. package/dist/src/schemas/origin.v1.schema.json +68 -0
  158. package/dist/src/schemas/policy-floor.v1.schema.json +29 -0
  159. package/dist/src/schemas/publication.v1.schema.json +31 -0
  160. package/dist/src/schemas/revocation.v1.schema.json +39 -0
  161. package/dist/src/schemas/submission.v1.schema.json +61 -0
  162. package/dist/src/store/def-source.d.ts +52 -0
  163. package/dist/src/store/def-source.js +335 -0
  164. package/dist/src/store/index-file.d.ts +69 -0
  165. package/dist/src/store/index-file.js +151 -0
  166. package/dist/src/store/index.d.ts +27 -0
  167. package/dist/src/store/index.js +22 -0
  168. package/dist/src/store/ingestor.d.ts +43 -0
  169. package/dist/src/store/ingestor.js +211 -0
  170. package/dist/src/store/install.d.ts +228 -0
  171. package/dist/src/store/install.js +555 -0
  172. package/dist/src/store/instruction-source.d.ts +49 -0
  173. package/dist/src/store/instruction-source.js +298 -0
  174. package/dist/src/store/origin-evidence.d.ts +21 -0
  175. package/dist/src/store/origin-evidence.js +66 -0
  176. package/dist/src/store/pre-commit-verifier.d.ts +68 -0
  177. package/dist/src/store/pre-commit-verifier.js +418 -0
  178. package/dist/src/store/resolve.d.ts +138 -0
  179. package/dist/src/store/resolve.js +363 -0
  180. package/dist/src/store/types.d.ts +288 -0
  181. package/dist/src/store/types.js +356 -0
  182. package/dist/src/types.d.ts +45 -11
  183. package/dist/src/untar.d.ts +8 -23
  184. package/dist/src/untar.js +10 -136
  185. package/docs/agent-runner.md +86 -0
  186. package/docs/authoring.md +57 -6
  187. package/docs/bundles.md +250 -0
  188. package/docs/cli.md +1171 -97
  189. package/docs/crypto.md +816 -0
  190. package/docs/design.md +342 -20
  191. package/docs/embedding.md +132 -25
  192. package/docs/wire-contracts.md +380 -0
  193. package/package.json +6 -1
  194. package/plugins/claude-code/.claude-plugin/marketplace.json +14 -0
  195. package/plugins/claude-code/plugin/.claude-plugin/plugin.json +8 -0
  196. package/plugins/claude-code/plugin/.mcp.json +14 -0
  197. package/plugins/claude-code/plugin/hooks/hooks.json +26 -0
  198. package/plugins/claude-code/plugin/hooks/session-end.sh +40 -0
  199. package/plugins/claude-code/plugin/hooks/session-start.sh +52 -0
  200. package/plugins/claude-code/plugin/skills/author/SKILL.md +181 -0
  201. package/plugins/claude-code/plugin/skills/conduct/SKILL.md +106 -0
  202. package/plugins/claude-code/plugin/skills/shift/SKILL.md +105 -0
  203. package/plugins/codex/.agents/plugins/marketplace.json +21 -0
  204. package/plugins/codex/plugins/owenloop/.codex-plugin/plugin.json +7 -0
  205. package/plugins/codex/plugins/owenloop/.mcp.json +20 -0
  206. package/plugins/codex/plugins/owenloop/hooks/hooks.json +26 -0
  207. package/plugins/codex/plugins/owenloop/hooks/session-end.sh +40 -0
  208. package/plugins/codex/plugins/owenloop/hooks/session-start.sh +52 -0
  209. package/plugins/codex/plugins/owenloop/skills/author/SKILL.md +181 -0
  210. package/plugins/codex/plugins/owenloop/skills/conduct/SKILL.md +106 -0
  211. package/plugins/codex/plugins/owenloop/skills/shift/SKILL.md +105 -0
@@ -0,0 +1,157 @@
1
+ /**
2
+ * Type-level definitions for the versioned records carried in DSSE envelopes.
3
+ *
4
+ * This module defines shapes only. Signing, verification, enrollment, revocation
5
+ * processing, scope attenuation, and policy evaluation belong to later layers.
6
+ * Field manifests intentionally sit beside each type: TypeScript checks the
7
+ * manifest against the type, while the wire-contract test checks the manifest
8
+ * against the checked-in JSON Schema. Neither side is generated from the other,
9
+ * so a drift changes a deliberate check into a failure instead of being hidden.
10
+ */
11
+ import { PAYLOAD_TYPE_ENROLLMENT_GRANT, PAYLOAD_TYPE_ORIGIN, PAYLOAD_TYPE_POLICY_FLOOR, PAYLOAD_TYPE_PUBLICATION, PAYLOAD_TYPE_REVOCATION, PAYLOAD_TYPE_SUBMISSION, } from "./dsse.js";
12
+ export const SUBMISSION_FIELDS = {
13
+ run: 'required',
14
+ workflow: 'required',
15
+ defDigest: 'required',
16
+ step: 'required',
17
+ key: 'required',
18
+ index: 'optional',
19
+ produced: 'required',
20
+ consumedFingerprint: 'required',
21
+ producerKeyId: 'required',
22
+ timestamp: 'required',
23
+ };
24
+ export const PUBLICATION_FIELDS = {
25
+ digest: 'required',
26
+ name: 'required',
27
+ version: 'required',
28
+ publisherKeyId: 'required',
29
+ timestamp: 'required',
30
+ };
31
+ export const ORIGIN_FIELDS = {
32
+ digest: 'required',
33
+ name: 'required',
34
+ version: 'required',
35
+ source: 'required',
36
+ attesterKeyId: 'required',
37
+ timestamp: 'required',
38
+ };
39
+ export const ORIGIN_SOURCE_GIT_FIELDS = {
40
+ kind: 'required',
41
+ repo: 'required',
42
+ commit: 'required',
43
+ };
44
+ export const ORIGIN_SOURCE_CONSOLE_FIELDS = {
45
+ kind: 'required',
46
+ user: 'required',
47
+ };
48
+ export const ORIGIN_SOURCE_AGENT_FIELDS = {
49
+ kind: 'required',
50
+ agent: 'required',
51
+ session: 'required',
52
+ };
53
+ export const SUBMISSION_PRODUCED_FIELDS = {
54
+ artifact: 'required',
55
+ version: 'required',
56
+ valueDigest: 'required',
57
+ };
58
+ export const ENROLLMENT_GRANT_FIELDS = {
59
+ newKey: 'required',
60
+ principal: 'required',
61
+ scope: 'required',
62
+ grantedBy: 'required',
63
+ validFrom: 'required',
64
+ };
65
+ export const ENROLLMENT_KEY_FIELDS = {
66
+ keyid: 'required',
67
+ keyType: 'required',
68
+ openSshPublicKey: 'required',
69
+ comment: 'optional',
70
+ };
71
+ export const PRINCIPAL_REFERENCE_FIELDS = {
72
+ kind: 'required',
73
+ id: 'required',
74
+ };
75
+ export const GRANT_SCOPE_FIELDS = {
76
+ pools: 'required',
77
+ labels: 'required',
78
+ namespaces: 'required',
79
+ delegation: 'required',
80
+ };
81
+ export const GRANT_DELEGATION_DENIED_FIELDS = {
82
+ allowed: 'required',
83
+ };
84
+ export const GRANT_DELEGATION_ALLOWED_FIELDS = {
85
+ allowed: 'required',
86
+ maxDepth: 'required',
87
+ };
88
+ export const REVOCATION_FIELDS = {
89
+ revokedKey: 'required',
90
+ principal: 'required',
91
+ revokedBy: 'required',
92
+ issuedAt: 'required',
93
+ effectiveFrom: 'required',
94
+ backdated: 'required',
95
+ reason: 'optional',
96
+ };
97
+ export const POLICY_FLOOR_RECORD_FIELDS = {
98
+ org: 'required',
99
+ issuedAt: 'required',
100
+ signedBy: 'required',
101
+ floor: 'required',
102
+ preset: 'optional',
103
+ };
104
+ export const POLICY_FLOOR_FIELDS = {
105
+ trustMode: 'required',
106
+ unsignedDefs: 'required',
107
+ unsignedArtifacts: 'required',
108
+ originRules: 'required',
109
+ };
110
+ /** The existing frozen reference-mode Order is the fifth launch contract. */
111
+ export const ORDER_FIELDS = {
112
+ run: 'required',
113
+ workflow: 'required',
114
+ step: 'required',
115
+ key: 'required',
116
+ index: 'optional',
117
+ defDigest: 'required',
118
+ inputs: 'required',
119
+ outputs: 'required',
120
+ workdir: 'optional',
121
+ model: 'optional',
122
+ worker: 'optional',
123
+ judge: 'optional',
124
+ spec: 'optional',
125
+ x: 'optional',
126
+ consumes: 'required',
127
+ consumedFingerprint: 'optional',
128
+ owes: 'required',
129
+ consumesProof: 'optional',
130
+ cause: 'optional',
131
+ };
132
+ /** Indexed access pins the already-emitted nested Order shape without cloning it. */
133
+ export const ORDER_OWED_FIELDS = {
134
+ path: 'required',
135
+ version: 'optional',
136
+ judgmentRejects: 'required',
137
+ schemaRejects: 'required',
138
+ reasons: 'required',
139
+ proof: 'optional',
140
+ };
141
+ export const ORDER_REASON_FIELDS = {
142
+ at: 'required',
143
+ action: 'required',
144
+ kind: 'required',
145
+ by: 'required',
146
+ text: 'required',
147
+ fromVersion: 'optional',
148
+ };
149
+ /** Bind every record definition in this package to a frozen DSSE media type. */
150
+ export const RECORD_PAYLOAD_TYPES = {
151
+ enrollmentGrant: PAYLOAD_TYPE_ENROLLMENT_GRANT,
152
+ revocation: PAYLOAD_TYPE_REVOCATION,
153
+ submission: PAYLOAD_TYPE_SUBMISSION,
154
+ policyFloor: PAYLOAD_TYPE_POLICY_FLOOR,
155
+ origin: PAYLOAD_TYPE_ORIGIN,
156
+ publication: PAYLOAD_TYPE_PUBLICATION,
157
+ };
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Pure enrollment-scope attenuation arithmetic.
3
+ *
4
+ * This module decides whether a child enrollment grant is no wider than the
5
+ * scope already held by its signer, and whether an effective scope permits one
6
+ * requested pool, label, or namespace. The module deliberately does not read
7
+ * keys, verify signatures, or perform filesystem or network I/O; chain.ts owns
8
+ * those concerns.
9
+ */
10
+ import type { GrantDelegation, GrantScope } from './records.ts';
11
+ /** One scope axis: an explicit allow-list or the all-values identity. */
12
+ export type ScopeAxis = string[] | '*';
13
+ /** Whether a child axis is contained by a parent's effective axis. */
14
+ export declare function axisPermits(parent: ScopeAxis, child: ScopeAxis): boolean;
15
+ /**
16
+ * Check whether a child delegation declaration is permitted by its parent.
17
+ * `maxDepth: N` means a grant signed by that key may delegate at most N - 1
18
+ * further levels; zero therefore permits only non-delegating child grants.
19
+ */
20
+ export declare function delegationPermits(parent: GrantDelegation, child: GrantDelegation): {
21
+ ok: true;
22
+ } | {
23
+ ok: false;
24
+ reason: string;
25
+ };
26
+ /** Check every axis and the delegation limit in one attenuation decision. */
27
+ export declare function attenuate(parent: GrantScope, child: GrantScope): {
28
+ ok: true;
29
+ } | {
30
+ ok: false;
31
+ reason: string;
32
+ };
33
+ /** The identity scope held by the local organization root anchor. */
34
+ export declare const ORG_ROOT_SCOPE: GrantScope;
35
+ /**
36
+ * Check whether a producer demand is contained by an effective grant scope.
37
+ * Omitted demand fields are not constrained; present fields must be allowed by
38
+ * their corresponding axis.
39
+ */
40
+ export declare function scopePermits(scope: GrantScope, demand: {
41
+ pool?: string;
42
+ label?: string;
43
+ namespace?: string;
44
+ }): {
45
+ ok: true;
46
+ } | {
47
+ ok: false;
48
+ reason: string;
49
+ };
@@ -0,0 +1,83 @@
1
+ /**
2
+ * Pure enrollment-scope attenuation arithmetic.
3
+ *
4
+ * This module decides whether a child enrollment grant is no wider than the
5
+ * scope already held by its signer, and whether an effective scope permits one
6
+ * requested pool, label, or namespace. The module deliberately does not read
7
+ * keys, verify signatures, or perform filesystem or network I/O; chain.ts owns
8
+ * those concerns.
9
+ */
10
+ /** Whether a child axis is contained by a parent's effective axis. */
11
+ export function axisPermits(parent, child) {
12
+ if (parent === '*')
13
+ return true;
14
+ if (child === '*')
15
+ return false;
16
+ const allowed = new Set(parent);
17
+ return child.every((value) => allowed.has(value));
18
+ }
19
+ /**
20
+ * Check whether a child delegation declaration is permitted by its parent.
21
+ * `maxDepth: N` means a grant signed by that key may delegate at most N - 1
22
+ * further levels; zero therefore permits only non-delegating child grants.
23
+ */
24
+ export function delegationPermits(parent, child) {
25
+ if (!parent.allowed) {
26
+ return { ok: false, reason: 'parent delegation is not allowed to sign grants' };
27
+ }
28
+ if (parent.maxDepth === 'unbounded')
29
+ return { ok: true };
30
+ if (!child.allowed)
31
+ return { ok: true };
32
+ if (child.maxDepth === 'unbounded') {
33
+ return {
34
+ ok: false,
35
+ reason: `child delegation is unbounded but parent permits at most ${parent.maxDepth - 1} further level(s)`,
36
+ };
37
+ }
38
+ if (child.maxDepth > parent.maxDepth - 1) {
39
+ return {
40
+ ok: false,
41
+ reason: `child delegation depth ${child.maxDepth} exceeds parent limit ${parent.maxDepth - 1}`,
42
+ };
43
+ }
44
+ return { ok: true };
45
+ }
46
+ /** Check every axis and the delegation limit in one attenuation decision. */
47
+ export function attenuate(parent, child) {
48
+ for (const axis of ['pools', 'labels', 'namespaces']) {
49
+ if (!axisPermits(parent[axis], child[axis])) {
50
+ const parentText = parent[axis] === '*' ? '*' : `[${parent[axis].join(', ')}]`;
51
+ const childText = child[axis] === '*' ? '*' : `[${child[axis].join(', ')}]`;
52
+ return { ok: false, reason: `${axis} scope widens from ${parentText} to ${childText}` };
53
+ }
54
+ }
55
+ return delegationPermits(parent.delegation, child.delegation);
56
+ }
57
+ /** The identity scope held by the local organization root anchor. */
58
+ export const ORG_ROOT_SCOPE = {
59
+ pools: '*',
60
+ labels: '*',
61
+ namespaces: '*',
62
+ delegation: { allowed: true, maxDepth: 'unbounded' },
63
+ };
64
+ function axisContains(axis, value) {
65
+ return axis === '*' || axis.includes(value);
66
+ }
67
+ /**
68
+ * Check whether a producer demand is contained by an effective grant scope.
69
+ * Omitted demand fields are not constrained; present fields must be allowed by
70
+ * their corresponding axis.
71
+ */
72
+ export function scopePermits(scope, demand) {
73
+ if (demand.pool !== undefined && !axisContains(scope.pools, demand.pool)) {
74
+ return { ok: false, reason: `pool '${demand.pool}' is outside the granted scope` };
75
+ }
76
+ if (demand.label !== undefined && !axisContains(scope.labels, demand.label)) {
77
+ return { ok: false, reason: `label '${demand.label}' is outside the granted scope` };
78
+ }
79
+ if (demand.namespace !== undefined && !axisContains(scope.namespaces, demand.namespace)) {
80
+ return { ok: false, reason: `namespace '${demand.namespace}' is outside the granted scope` };
81
+ }
82
+ return { ok: true };
83
+ }
@@ -0,0 +1,171 @@
1
+ /**
2
+ * SSHSIG signing/verification through stock OpenSSH, behind one async
3
+ * `Signer` interface.
4
+ *
5
+ * **Why stock OpenSSH (and not a pure-JS SSHSIG implementation):** invoking
6
+ * `ssh-keygen -Y sign` / `ssh-keygen -Y verify` gives byte-level
7
+ * interoperability with the system verifier, adds no cryptographic
8
+ * parser/encoder dependency, and delegates SSHSIG format and `allowed_signers`
9
+ * policy semantics to maintained OpenSSH code. The portability cost is an
10
+ * external runtime requirement: `ssh-keygen` must support `-Y`. Support is
11
+ * PROBED (a harmless capability invocation), never inferred from a version
12
+ * string; when unavailable the probe result is an actionable error.
13
+ *
14
+ * **Secrecy discipline.** Private key material never appears in argv, captured
15
+ * stdout/stderr, thrown messages, or logs:
16
+ * - every invocation is `shell: false` (argv is a vector, never a shell line);
17
+ * - the message bytes ride on child stdin; the private key rides only as a
18
+ * `-f <path>` argument (a PATH — never the key contents);
19
+ * - child stdout/stderr is captured only where it is public by nature (the
20
+ * armored SSH signature; verification status). A verification failure
21
+ * throws a FIXED diagnostic that never interpolates child output.
22
+ *
23
+ * **Signer semantics.** `verify` returns a `VerifiedSignature` descriptor on a
24
+ * successful OpenSSH verification against the configured principal +
25
+ * `allowed_signers` content, or `null` on a normal verification miss. A
26
+ * tool/configuration failure (no binary, missing `-Y` support, timeout,
27
+ * oversized output) THROWS — a miss and a broken toolchain are different
28
+ * facts. Authorization is decided by OpenSSH itself; a signature's `keyid`
29
+ * (candidate hint) is never treated as identity.
30
+ */
31
+ /** The result of signing: which key signed (`keyid`) and the signature bytes. */
32
+ export interface DetachedSignature {
33
+ /** The signer's keyid (the `SHA256:<b64>` public-key fingerprint). */
34
+ keyid: string;
35
+ /**
36
+ * The signature bytes. For the SSH signer this is the ARMORED SSH signature
37
+ * text (`-----BEGIN SSH SIGNATURE-----` …) as UTF-8 bytes — the armored form
38
+ * is what OpenSSH consumes and emits, and it is public information.
39
+ */
40
+ sig: Buffer;
41
+ }
42
+ /** Describes a signature that verified — non-secret public descriptors only. */
43
+ export interface VerifiedSignature {
44
+ /** The verified signer's keyid (fingerprint of the verifying public key). */
45
+ keyid: string;
46
+ /** The SSH principal (signer identity) OpenSSH matched in allowed_signers. */
47
+ principal: string;
48
+ /** The format that produced the signature, e.g. `'sshsig'`. */
49
+ format: 'sshsig';
50
+ }
51
+ /**
52
+ * The async, format-neutral signer contract. DSSE depends only on this
53
+ * interface, so a future Sigstore signer can implement the same contract
54
+ * without changing DSSE. `sign` produces a detached signature over EXACT
55
+ * bytes; `verify` returns the verified descriptor or `null` on a normal miss
56
+ * (tool failures throw).
57
+ */
58
+ export interface Signer {
59
+ sign(exactBytes: Buffer): Promise<DetachedSignature>;
60
+ verify(exactBytes: Buffer, signature: Buffer): Promise<VerifiedSignature | null>;
61
+ }
62
+ /** The SSH signer's configuration. */
63
+ export interface SshSignerConfig {
64
+ /** The SSHSIG namespace (the `-n` domain string). Required. */
65
+ namespace: string;
66
+ /**
67
+ * Signing key handle — a filesystem path to a PRIVATE key (or to a public
68
+ * key whose private half is reachable through ssh-agent). Present ⇒ this
69
+ * signer can sign; absent ⇒ verify-only.
70
+ */
71
+ signKeyPath?: string;
72
+ /**
73
+ * Verification context: the expected signer principal (`-I`) and the raw
74
+ * `allowed_signers` file content. Present ⇒ this signer can verify.
75
+ */
76
+ verify?: {
77
+ principal: string;
78
+ allowedSignersText: string;
79
+ };
80
+ /** Injectable process adapter (hermetic tests). */
81
+ process?: SshProcessAdapter;
82
+ /** Injectable temp-dir factory (hermetic tests). */
83
+ tempDir?: (prefix: string) => string;
84
+ /** Per-invocation timeout in ms (default 10s). */
85
+ timeoutMs?: number;
86
+ }
87
+ /**
88
+ * The minimal process seam the SSH signer needs. Defaults to a `spawn` wrapper
89
+ * (`shell: false`, never inherits stdio); tests inject a fake to assert argv
90
+ * and stdin secrecy without a real `ssh-keygen`.
91
+ */
92
+ export interface SshProcessAdapter {
93
+ run(cmd: string, args: string[], opts: {
94
+ stdin?: Buffer;
95
+ timeoutMs: number;
96
+ maxBuffer?: number;
97
+ }): Promise<{
98
+ status: number | null;
99
+ stdout: Buffer;
100
+ stderr: Buffer;
101
+ timedOut: boolean;
102
+ truncated: boolean;
103
+ }>;
104
+ /** Synchronous, non-secret feature probe used by createSshSigner. */
105
+ probe?(cmd: string, args: string[], opts: {
106
+ timeoutMs: number;
107
+ }): {
108
+ status: number | null;
109
+ stderr: Buffer;
110
+ errorCode?: string;
111
+ timedOut?: boolean;
112
+ };
113
+ }
114
+ /** Thrown for SSHSIG tool/configuration failures. Message is fixed, non-secret. */
115
+ export declare class SshSignerError extends Error {
116
+ constructor(message: string);
117
+ }
118
+ /** The default `spawn`-based adapter: `shell: false`, captured stdio, timeout + output cap. */
119
+ export declare const defaultSshProcess: SshProcessAdapter;
120
+ export declare function probeSshKeygenY(adapter?: SshProcessAdapter, tempDir?: (prefix: string) => string): {
121
+ ok: boolean;
122
+ detail: string;
123
+ };
124
+ /** Reset the cached capability (tests only). */
125
+ export declare function resetSshKeygenProbe(): void;
126
+ /**
127
+ * The OpenSSH SSHSIG signer. Construct via `createSshSigner`. Signing and
128
+ * verification are separate capabilities configured at construction; using an
129
+ * unconfigured capability throws a fixed `SshSignerError`.
130
+ */
131
+ export declare class SshSigner implements Signer {
132
+ private readonly config;
133
+ private readonly proc;
134
+ private readonly makeTempDir;
135
+ /** The verification temp dir (created lazily), removed in `dispose`. */
136
+ private verifyDir;
137
+ constructor(config: SshSignerConfig);
138
+ /**
139
+ * Sign `exactBytes` by placing the private key path in `-f`, the configured
140
+ * namespace in `-n`, and the message on stdin. The armored SSH signature is
141
+ * captured from stdout (public information). Payload and private bytes never
142
+ * appear in argv.
143
+ */
144
+ sign(exactBytes: Buffer): Promise<DetachedSignature>;
145
+ /**
146
+ * Verify `exactBytes` against a detached armored signature. Writes the
147
+ * armored signature and the raw `allowed_signers` text to temporary
148
+ * NON-SECRET files, passes the expected principal with `-I`, the namespace
149
+ * with `-n`, and the message on stdin.
150
+ *
151
+ * Zero exit ⇒ valid: returns `{ keyid, principal, format: 'sshsig' }`.
152
+ * A normal verification miss ⇒ `null`. Tool/configuration failures throw a
153
+ * fixed diagnostic that includes no child output.
154
+ */
155
+ verify(exactBytes: Buffer, signature: Buffer): Promise<VerifiedSignature | null>;
156
+ /** Remove the verification temp dir. */
157
+ dispose(): void;
158
+ }
159
+ /**
160
+ * Create an `SshSigner` from a config. Verifies the capability probe once
161
+ * (cached for the process lifetime) and throws an actionable error when the
162
+ * system `ssh-keygen` lacks `-Y`.
163
+ */
164
+ export declare function createSshSigner(config: SshSignerConfig): SshSigner;
165
+ /**
166
+ * Validate that a candidate SSH key is Ed25519 by reading its public key text
167
+ * (private bytes are never read). Throws a fixed error for non-Ed25519 keys —
168
+ * WP-A2 rejects them even though `allowed_signers` can represent other stock
169
+ * key types.
170
+ */
171
+ export declare function assertEd25519PubText(pubText: string, label: string): void;