@joe-broadhead/opencode-mem 0.9.12 → 0.11.2
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 +1934 -2
- package/README.md +29 -17
- package/SECURITY.md +3 -1
- package/docs/agent-instructions.md +17 -0
- package/docs/agent-protocol.md +8 -8
- package/docs/permissions.md +22 -4
- package/package.json +7923 -217
- package/shared/page-paths.js +44 -0
- package/skills/mem.pages/SKILL.md +8 -1
- package/skills/mem.usage/SKILL.md +15 -15
- package/src/action-grant-keys.js +159 -0
- package/src/action-grant.js +439 -0
- package/src/actions.js +1690 -0
- package/src/backend/records.js +25 -2
- package/src/backend/v3.js +76 -22
- package/src/call-shapes.js +17 -16
- package/src/collector-lock.js +533 -62
- package/src/collector-service.js +153 -26
- package/src/collector.js +627 -33
- package/src/config.js +79 -6
- package/src/connect.js +106 -8
- package/src/credentials.js +123 -25
- package/src/events.js +174 -3
- package/src/forget-turn.js +141 -0
- package/src/host-refusal.js +78 -0
- package/src/index.js +209 -22
- package/src/jobs/host.js +557 -0
- package/src/ops/codes.js +110 -0
- package/src/ops/copy-lineage.js +42 -0
- package/src/ops/index.js +28 -0
- package/src/ops/space-ops.js +1936 -0
- package/src/outlinks.js +103 -0
- package/src/p2-reservation.js +151 -0
- package/src/permissions.js +30 -0
- package/src/plugins/descriptor.js +62 -0
- package/src/plugins/discovery.js +318 -0
- package/src/plugins/grants.js +178 -0
- package/src/plugins/locate.js +319 -0
- package/src/plugins/manifest.js +1162 -0
- package/src/plugins/source-contract/index.js +34 -0
- package/src/plugins/source-contract/policy.js +102 -0
- package/src/plugins/source-contract/vendor/PROVENANCE.json +17 -0
- package/src/plugins/source-contract/vendor/RELEASE-SHA256SUMS +3 -0
- package/src/plugins/source-contract/vendor/RELEASE.json +17 -0
- package/src/plugins/source-contract/vendor/SHA256SUMS +41 -0
- package/src/plugins/source-contract/vendor/THIRD-PARTY-NOTICES.md +35 -0
- package/src/plugins/source-contract/vendor/broker-client.js +93 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-3M5PAKSS.js +84 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-4ERCA4TK.js +185 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-6HDIB2SA.js +183 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-ELPJD3ND.js +10 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-HLVAKAYG.js +10 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-I2RXJJJM.js +81 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-KWEWSZ4V.js +505 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-KYWBTAF4.js +182 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-Q3RQA5J2.js +249 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-RRUAIQ4I.js +156 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-RYNKNCPP.js +165 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-W5SHR7DQ.js +9477 -0
- package/src/plugins/source-contract/vendor/chunks/chunk-ZUKF7P6U.js +653 -0
- package/src/plugins/source-contract/vendor/cursor.js +26 -0
- package/src/plugins/source-contract/vendor/descriptor.js +34 -0
- package/src/plugins/source-contract/vendor/events.js +257 -0
- package/src/plugins/source-contract/vendor/index.js +10 -0
- package/src/plugins/source-contract/vendor/params.js +22 -0
- package/src/plugins/source-contract/vendor/permission.js +28 -0
- package/src/plugins/source-contract/vendor/pick.js +22 -0
- package/src/plugins/source-contract/vendor/read.js +29 -0
- package/src/plugins/source-contract/vendor/registry.js +23 -0
- package/src/plugins/source-contract/vendor/schema.js +17 -0
- package/src/plugins/source-contract/vendor/schemas/output.agenda.json +96 -0
- package/src/plugins/source-contract/vendor/schemas/output.countdown.json +28 -0
- package/src/plugins/source-contract/vendor/schemas/output.image.json +28 -0
- package/src/plugins/source-contract/vendor/schemas/output.inbox.json +84 -0
- package/src/plugins/source-contract/vendor/schemas/output.links.json +46 -0
- package/src/plugins/source-contract/vendor/schemas/output.list.json +57 -0
- package/src/plugins/source-contract/vendor/schemas/output.metric.json +61 -0
- package/src/plugins/source-contract/vendor/schemas/output.note.json +14 -0
- package/src/plugins/source-contract/vendor/schemas/output.progress.json +50 -0
- package/src/plugins/source-contract/vendor/schemas/output.record.json +38 -0
- package/src/plugins/source-contract/vendor/schemas/output.table.json +61 -0
- package/src/plugins/source-contract/vendor/schemas/output.thread.json +62 -0
- package/src/plugins/source-contract/vendor/schemas/sources.json +819 -0
- package/src/plugins/source-contract/vendor/schemas.js +19 -0
- package/src/plugins/source-contract/vendor/tools-rpc.js +42 -0
- package/src/plugins/verify.js +56 -0
- package/src/protocol.js +21 -5
- package/src/recall.js +104 -5
- package/src/records.js +61 -2
- package/src/requests.js +216 -0
- package/src/runtime.js +89 -7
- package/src/setup-time.js +68 -0
- package/src/skills.js +230 -8
- package/src/source-ids.js +25 -0
- package/src/sources/declaration.js +365 -0
- package/src/sources/reads.js +772 -0
- package/src/sources/rpc.js +151 -0
- package/src/sources.js +409 -90
- package/src/spaces.js +283 -11
- package/src/spool.js +61 -4
- package/src/stated.js +10 -5
- package/src/storable.js +139 -0
- package/src/tools/commitments.js +47 -5
- package/src/tools/held-write.js +36 -13
- package/src/tools/index.js +27 -0
- package/src/tools/ingest.js +27 -2
- package/src/tools/memory.js +52 -14
- package/src/tools/page.js +95 -9
- package/src/tools/recall.js +208 -4
- package/src/tools/records-kit.js +2 -1
- package/src/tools/share.js +42 -3
- package/src/tools/shared.js +44 -4
- package/src/tools/space-lifecycle.js +278 -0
- package/src/tools/spaces.js +373 -29
- package/src/tools/status.js +9 -2
- package/src/tools/wiki.js +34 -4
- package/src/util.js +110 -6
- package/src/vendor/source-contract/README.md +24 -0
- package/src/vendor/source-contract/THIRD-PARTY-NOTICES.md +35 -0
- package/src/vendor/source-contract/VENDOR.json +81 -0
- package/src/vendor/source-contract/chunks/chunk-3M5PAKSS.js +84 -0
- package/src/vendor/source-contract/chunks/chunk-6HDIB2SA.js +183 -0
- package/src/vendor/source-contract/chunks/chunk-HLVAKAYG.js +10 -0
- package/src/vendor/source-contract/chunks/chunk-I2RXJJJM.js +81 -0
- package/src/vendor/source-contract/chunks/chunk-KWEWSZ4V.js +505 -0
- package/src/vendor/source-contract/chunks/chunk-W5SHR7DQ.js +9477 -0
- package/src/vendor/source-contract/chunks/chunk-ZUKF7P6U.js +653 -0
- package/src/vendor/source-contract/cursor.js +26 -0
- package/src/vendor/source-contract/events.js +257 -0
- package/src/vendor/source-contract/registry.js +23 -0
- package/src/vendor/source-contract/tools-rpc.js +42 -0
- package/src/views/access-reads.js +256 -0
- package/src/views/communities.js +77 -0
- package/src/views/contracts.js +1183 -36
- package/src/views/inbox-bytes.js +103 -0
- package/src/views/overdue.js +1 -1
- package/src/views/profile.js +31 -0
- package/src/views/receipt.js +81 -0
- package/src/views/records-reads.js +869 -37
- package/src/views/rpc.js +159 -11
- package/src/views/shape.js +8 -5
- package/views/memory.html +16 -3
- package/views/pages.html +2 -2
- package/views/remembered.html +130 -0
|
@@ -0,0 +1,1162 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The fixed frame of plugin-declared Memory (DESIGN-PLUGIN-MEMORY §1.2, §5.6,
|
|
3
|
+
* and DESIGN-MEMORY-JOBS §9 for schema v2): the `memory-plugin.v2` schema of a
|
|
4
|
+
* plugin's `package.json#memory`, the read-verb allowlist with the write-verb
|
|
5
|
+
* check on every token, the connector's identity, reads and scope inputs, its
|
|
6
|
+
* templates, and the canonical digest (RFC 8785 JSON, SHA-256).
|
|
7
|
+
*
|
|
8
|
+
* One module, three copies kept identical by scripts/check-copies.mjs:
|
|
9
|
+
* records/src/plugins/manifest.js for the records service, which validates
|
|
10
|
+
* every report again, and src/plugins/manifest.js for the plugin's discovery.
|
|
11
|
+
* Its only import is the shape guard, which sits beside both copies.
|
|
12
|
+
*
|
|
13
|
+
* Nothing here names a plugin or a source. A manifest that fails anywhere is
|
|
14
|
+
* invalid as a whole: `validateManifest` answers the first reason, and
|
|
15
|
+
* nothing in it is used. Plugin text is data: it is length-limited and
|
|
16
|
+
* shape-checked here, and never enters a prompt, a tool description, a skill
|
|
17
|
+
* or the protocol.
|
|
18
|
+
*/
|
|
19
|
+
import { createHash } from "node:crypto"
|
|
20
|
+
import { shapes } from "../shapes.js"
|
|
21
|
+
|
|
22
|
+
/** The schema's major version. Memory accepts this one and the one before it (v1's `sources` + `routines`). */
|
|
23
|
+
export const SCHEMA_VERSION = 2
|
|
24
|
+
export const SCHEMA_VERSIONS = Object.freeze([1, 2])
|
|
25
|
+
/** The `events_list` contract a declared source must speak (§9.3). */
|
|
26
|
+
export const SOURCE_CONTRACT = 2
|
|
27
|
+
/**
|
|
28
|
+
* The event fields a `perUnit` scope input may take its value from (§9.1 C).
|
|
29
|
+
* `thread` is written `<scheme>-thread:<channel id>:<thread ts>`, so its channel
|
|
30
|
+
* and its ts are the two parts of it, never anything parsed from an event's text.
|
|
31
|
+
*/
|
|
32
|
+
export const PER_UNIT_FIELDS = Object.freeze(["external_id", "thread_channel", "thread_ts"])
|
|
33
|
+
|
|
34
|
+
/** The allowed verbs (§9.1 A). `fetch` is not one: it can send data out. */
|
|
35
|
+
export const READ_VERBS = Object.freeze(["read", "get", "list", "search", "lookup", "view", "describe", "history", "query", "count"])
|
|
36
|
+
/**
|
|
37
|
+
* The write verbs (§5.6): no token of a tail or op may be one of these.
|
|
38
|
+
*
|
|
39
|
+
* The name check cannot prove a tool is read-only: a tool named `get_x` may
|
|
40
|
+
* write. It refuses the obvious names; the real defences are that a binding's
|
|
41
|
+
* session allows exactly the grants the person confirmed (src/plugins/grants.js)
|
|
42
|
+
* and the plugin kit's recorded-assertion check, which fails a plugin's CI on
|
|
43
|
+
* any action its events_list asserts that its declaration does not list.
|
|
44
|
+
*/
|
|
45
|
+
export const WRITE_VERBS = Object.freeze([
|
|
46
|
+
"send", "post", "reply", "set", "add", "edit", "create", "update", "upsert", "delete", "remove", "trash", "modify", "patch", "insert",
|
|
47
|
+
"import", "export", "write", "put", "save", "publish", "share", "invite", "upload", "schedule", "react", "mark", "label", "pin",
|
|
48
|
+
"follow", "archive", "move", "merge", "close", "comment", "assign", "draft", "approve", "submit", "cancel", "revoke", "grant", "run",
|
|
49
|
+
"execute", "invoke", "purge", "destroy", "drop", "wipe", "erase", "transfer", "trigger", "kick",
|
|
50
|
+
"join", "leave", "ban", "mute", "toggle", "forward", "dispatch", "clear", "flush", "reset", "truncate", "overwrite", "apply",
|
|
51
|
+
])
|
|
52
|
+
/** Tokens that join two actions in one name (`read_and_delete`): refused whatever the verbs. */
|
|
53
|
+
export const CONJUNCTIONS = Object.freeze(["and", "then", "or"])
|
|
54
|
+
/** The deepest a declaration may nest (the schema needs 6), and the deepest canonical JSON goes. */
|
|
55
|
+
export const MAX_DEPTH = 12
|
|
56
|
+
const MAX_CANONICAL_DEPTH = 64
|
|
57
|
+
/** Namespaces no plugin may claim: Memory's own, the host's, and OpenCode's builtin tool ids. */
|
|
58
|
+
export const RESERVED_NAMESPACES = Object.freeze([
|
|
59
|
+
"mem", "opencode", "jobs", "execute", "codemode",
|
|
60
|
+
"bash", "read", "write", "edit", "glob", "grep", "list", "patch", "task", "todowrite", "todoread", "webfetch", "websearch", "skill", "question", "lsp", "shell", "plan", "build",
|
|
61
|
+
])
|
|
62
|
+
/** The event kinds of the `events_list` contract, with v2's `snapshot` (§1.4). */
|
|
63
|
+
export const EVENT_KINDS = Object.freeze(["message", "meeting", "session", "bookmark", "issue", "pr", "commit", "doc", "event", "snapshot"])
|
|
64
|
+
/** The `render` engine's placeholders (§4.3), and only these. */
|
|
65
|
+
export const RENDER_PLACEHOLDERS = Object.freeze(["title", "count", "participants", "first_at", "last_at", "cite", "url", "text"])
|
|
66
|
+
/** The output kinds (§4.5). `section:<Heading>` is written with its heading. */
|
|
67
|
+
export const PROPOSAL_OUTPUTS = Object.freeze(["decision", "fact", "commitment_open", "commitment_close", "procedure", "person", "link"])
|
|
68
|
+
|
|
69
|
+
export const MAX_SOURCES = 8
|
|
70
|
+
export const MAX_ROUTINES = 16
|
|
71
|
+
export const MAX_READS = 16
|
|
72
|
+
export const MAX_TEMPLATES = 8
|
|
73
|
+
export const MAX_GRANTS = 8
|
|
74
|
+
export const MAX_SCOPE_KEYS = 8
|
|
75
|
+
export const MAX_INPUT_BYTES = 512
|
|
76
|
+
export const MAX_HINTS = 1500
|
|
77
|
+
export const MAX_RENDER_ITEMS = 50
|
|
78
|
+
export const MAX_TOKENS_PER_RUN = 25_000
|
|
79
|
+
|
|
80
|
+
const ID = /^[a-z][a-z0-9-]{0,39}$/
|
|
81
|
+
const NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/
|
|
82
|
+
const LABEL = /^[a-z][a-z0-9_.:-]{0,63}$/
|
|
83
|
+
const LABEL_PREFIX = /^[a-z][a-z0-9_-]{0,31}$/
|
|
84
|
+
const METRIC = /^[a-z][a-z0-9_]{0,23}$/
|
|
85
|
+
const CONTROL = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/
|
|
86
|
+
const WINDOWS = ["1d", "7d", "31d"]
|
|
87
|
+
/** A host a templated `{url}` may point at: a domain, or `*.` and a domain. */
|
|
88
|
+
const HOST_PATTERN = /^(?:\*\.)?[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i
|
|
89
|
+
/**
|
|
90
|
+
* The multi-label public suffixes a person can register under but not *be*: a
|
|
91
|
+
* pattern of one of these names no site of theirs. A small embedded list, the
|
|
92
|
+
* common ones; a suffix it misses is caught by the registrable-domain rule.
|
|
93
|
+
*/
|
|
94
|
+
const PUBLIC_SUFFIXES = new Set([
|
|
95
|
+
"co.uk", "org.uk", "ac.uk", "gov.uk", "me.uk", "net.uk", "sch.uk", "ltd.uk", "plc.uk",
|
|
96
|
+
"com.au", "net.au", "org.au", "edu.au", "gov.au", "co.nz", "net.nz", "org.nz", "govt.nz",
|
|
97
|
+
"co.jp", "ne.jp", "or.jp", "go.jp", "co.kr", "or.kr", "co.in", "net.in", "org.in", "co.za",
|
|
98
|
+
"com.br", "net.br", "org.br", "com.mx", "com.ar", "com.co", "com.pe", "com.ve", "com.uy",
|
|
99
|
+
"com.tr", "com.cn", "com.tw", "com.hk", "com.sg", "com.my", "com.ph", "com.vn", "com.pk",
|
|
100
|
+
"com.ng", "com.sa", "com.eg", "com.ua", "com.pl", "com.es", "com.gr", "com.pt", "com.ro",
|
|
101
|
+
"co.id", "co.il", "co.ke", "co.th", "co.ae", "co.ma", "co.bw", "co.zw", "co.tz", "co.ug",
|
|
102
|
+
])
|
|
103
|
+
/** Hosts anyone can claim, or that hand a page to the next stranger: no evidence of the source. */
|
|
104
|
+
const SHARED_HOSTS = new Set([
|
|
105
|
+
"cloudfront.net", "amazonaws.com", "storage.googleapis.com", "blob.core.windows.net", "web.core.windows.net",
|
|
106
|
+
"herokuapp.com", "vercel.app", "netlify.app", "pages.dev", "workers.dev", "github.io", "githubusercontent.com",
|
|
107
|
+
"gitlab.io", "bitbucket.io", "appspot.com", "firebaseapp.com", "web.app", "azurewebsites.net", "elasticbeanstalk.com",
|
|
108
|
+
"onrender.com", "railway.app", "fly.dev", "deno.dev", "glitch.me", "repl.co", "surge.sh", "ngrok.io", "r2.dev",
|
|
109
|
+
"blogspot.com", "wordpress.com", "wixsite.com", "translate.goog", "ipfs.io", "dweb.link", "bit.ly", "tinyurl.com",
|
|
110
|
+
])
|
|
111
|
+
/** Measurement and advertising: a collected link to one of these is a beacon, not a source. */
|
|
112
|
+
const TRACKER_HOSTS = new Set([
|
|
113
|
+
"doubleclick.net", "google-analytics.com", "googletagmanager.com", "googleadservices.com", "googlesyndication.com",
|
|
114
|
+
"2mdn.net", "facebook.net", "scorecardresearch.com", "criteo.com", "taboola.com", "outbrain.com", "adnxs.com",
|
|
115
|
+
"hotjar.com", "segment.io", "mixpanel.com", "amplitude.com", "quantserve.com", "moatads.com", "adsrvr.org",
|
|
116
|
+
"casalemedia.com", "rubiconproject.com", "pubmatic.com", "openx.net", "clarity.ms", "branch.io", "appsflyer.com",
|
|
117
|
+
"adjust.com", "kochava.com", "smartadserver.com", "teads.tv", "yieldmo.com", "bat.bing.com",
|
|
118
|
+
])
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* The second-level labels a ccTLD hands out as registry rules (`com.de`,
|
|
122
|
+
* `gov.in`, `co.uk`): a pattern of one of these plus a two-letter country code
|
|
123
|
+
* names no site, and so does a wildcard on it. The embedded suffix list names
|
|
124
|
+
* the common ones; this rule is what catches one it misses.
|
|
125
|
+
*/
|
|
126
|
+
const EFFECTIVE_SLD = new Set([
|
|
127
|
+
"com", "co", "gov", "org", "net", "ac", "edu", "ne", "or", "go", "nic", "mil", "sch", "ltd", "plc",
|
|
128
|
+
"gen", "web", "biz", "info", "nom", "res", "idv", "gob", "gouv", "gv", "k12", "muni",
|
|
129
|
+
])
|
|
130
|
+
|
|
131
|
+
/** True when a two-label host is an effective-TLD rule: `<second level>.<ccTLD>`. */
|
|
132
|
+
function isEffectiveSldRule(labels) {
|
|
133
|
+
return labels.length === 2 && EFFECTIVE_SLD.has(labels[0]) && /^[a-z]{2}$/.test(labels[1])
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** The multi-label public suffix a host ends in, or null. */
|
|
137
|
+
function publicSuffixOf(labels) {
|
|
138
|
+
for (const size of [3, 2]) {
|
|
139
|
+
if (labels.length > size && PUBLIC_SUFFIXES.has(labels.slice(-size).join("."))) return labels.slice(-size).join(".")
|
|
140
|
+
}
|
|
141
|
+
return null
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/**
|
|
145
|
+
* Why a `urlHosts` pattern is too broad to mean anything, or null: a public
|
|
146
|
+
* suffix alone, a wildcard sitting on one, no registrable domain under a
|
|
147
|
+
* wildcard, a shared host, or a tracker.
|
|
148
|
+
*/
|
|
149
|
+
export function urlHostProblem(host) {
|
|
150
|
+
if (typeof host !== "string" || !HOST_PATTERN.test(host)) return "is not a host pattern (a domain such as slack.com, or *.slack.com)"
|
|
151
|
+
const bare = host.toLowerCase().replace(/^\*\./, "")
|
|
152
|
+
const labels = bare.split(".")
|
|
153
|
+
if (labels.length < 2) return "names no registrable domain (a host needs at least two labels)"
|
|
154
|
+
// §9.4: a label in punycode (`xn--…`) hides what the host actually is — another
|
|
155
|
+
// script, or a lookalike of the source's own name — so no pattern may carry one.
|
|
156
|
+
if (labels.some((label) => label.startsWith("xn--"))) return "is a punycode host (a label starting xn--), which hides what it is"
|
|
157
|
+
const suffix = publicSuffixOf(labels)
|
|
158
|
+
if (PUBLIC_SUFFIXES.has(bare)) return `is a public suffix (${bare}), which names no site`
|
|
159
|
+
if (isEffectiveSldRule(labels)) return `is an effective-TLD rule (${bare}), which names no site`
|
|
160
|
+
if (suffix && bare === suffix) return `is a public suffix (${suffix}), which names no site`
|
|
161
|
+
for (const listed of SHARED_HOSTS) if (bare === listed || bare.endsWith(`.${listed}`)) return `is a shared host (${listed}), which anyone can claim`
|
|
162
|
+
for (const listed of TRACKER_HOSTS) if (bare === listed || bare.endsWith(`.${listed}`)) return `is a tracker (${listed}), which is no source's destination`
|
|
163
|
+
return null
|
|
164
|
+
}
|
|
165
|
+
const CADENCES = ["daily", "weekly", "monthly"]
|
|
166
|
+
const ENGINES = ["render", "extract"]
|
|
167
|
+
const UNITS = ["event", "thread"]
|
|
168
|
+
|
|
169
|
+
class Invalid extends Error {}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* A plugin-supplied name, as a reason may echo it: letters, digits, _, . and
|
|
173
|
+
* - only, at most 40 characters, else a fixed word. Reasons are shown in the
|
|
174
|
+
* console and reach the records service; they never carry plugin text.
|
|
175
|
+
*/
|
|
176
|
+
function echo(name) {
|
|
177
|
+
const value = String(name ?? "")
|
|
178
|
+
return /^[A-Za-z0-9_.-]{1,40}$/.test(value) ? value : "(a name that is not shown)"
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** True when a JSON value nests deeper than `max` (arrays and objects), checked without recursion. */
|
|
182
|
+
function deeperThan(value, max) {
|
|
183
|
+
const stack = [[value, 0]]
|
|
184
|
+
while (stack.length) {
|
|
185
|
+
const [item, depth] = stack.pop()
|
|
186
|
+
if (item === null || typeof item !== "object") continue
|
|
187
|
+
if (depth >= max) return true
|
|
188
|
+
for (const child of Array.isArray(item) ? item : Object.values(item)) if (child !== null && typeof child === "object") stack.push([child, depth + 1])
|
|
189
|
+
}
|
|
190
|
+
return false
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function fail(message) {
|
|
194
|
+
throw new Invalid(message)
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
function isObject(value) {
|
|
198
|
+
return value !== null && typeof value === "object" && !Array.isArray(value)
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
function object(value, where) {
|
|
202
|
+
if (!isObject(value)) fail(`${where} must be an object`)
|
|
203
|
+
return value
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
function only(value, keys, where) {
|
|
207
|
+
for (const key of Object.keys(value)) if (!keys.includes(key)) fail(`${where} has an unknown field ${echo(key)}`)
|
|
208
|
+
}
|
|
209
|
+
|
|
210
|
+
function list(value, where, { min = 0, max }) {
|
|
211
|
+
if (!Array.isArray(value)) fail(`${where} must be a list`)
|
|
212
|
+
if (value.length < min) fail(`${where} needs at least ${min} item${min === 1 ? "" : "s"}`)
|
|
213
|
+
if (value.length > max) fail(`${where} has more than ${max} items`)
|
|
214
|
+
return value
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
function pattern(value, regex, where) {
|
|
218
|
+
if (typeof value !== "string" || !regex.test(value)) fail(`${where} must match ${regex.source}`)
|
|
219
|
+
return value
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
function integer(value, where, { min, max }) {
|
|
223
|
+
if (!Number.isInteger(value) || value < min || value > max) fail(`${where} must be a whole number from ${min} to ${max}`)
|
|
224
|
+
return value
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
function bool(value, where) {
|
|
228
|
+
if (typeof value !== "boolean") fail(`${where} must be true or false`)
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/** Display or template text: a string, at most `max` characters, no control characters, no unsafe shape. */
|
|
232
|
+
function text(value, where, { max, empty = false }) {
|
|
233
|
+
if (typeof value !== "string") fail(`${where} must be text`)
|
|
234
|
+
if (!empty && value.trim() === "") fail(`${where} must not be empty`)
|
|
235
|
+
if (value.length > max) fail(`${where} is longer than ${max} characters`)
|
|
236
|
+
if (CONTROL.test(value)) fail(`${where} has a control character`)
|
|
237
|
+
if (shapes(value).any) fail(`${where} has an unsafe shape (an instruction, a permission or a share)`)
|
|
238
|
+
return value
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** The tokens of a name: split on `_`, `.`, `-` and camelCase, lower case. */
|
|
242
|
+
function tokens(name) {
|
|
243
|
+
return String(name)
|
|
244
|
+
.split(/[_.\-]+/)
|
|
245
|
+
.flatMap((part) => part.split(/(?<=[a-z0-9])(?=[A-Z])/))
|
|
246
|
+
.map((part) => part.toLowerCase())
|
|
247
|
+
.filter(Boolean)
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
/**
|
|
251
|
+
* The forms a token may be a write verb in: itself, and without -ed, -ied,
|
|
252
|
+
* -d or -ing (a doubled last consonant undone). Plurals (-s, -es, -ies) and
|
|
253
|
+
* -er nouns are not: `labels`, `posts`, `sender` and `folder` are reads, and
|
|
254
|
+
* a compound such as `read_and_deletes` is refused by its conjunction.
|
|
255
|
+
*/
|
|
256
|
+
function stems(token) {
|
|
257
|
+
const out = new Set([token])
|
|
258
|
+
for (const [suffix, back] of [["ied", "y"], ["ed", ""], ["d", ""], ["ing", ""]]) {
|
|
259
|
+
if (!token.endsWith(suffix) || token.length <= suffix.length + 1) continue
|
|
260
|
+
const base = token.slice(0, -suffix.length) + back
|
|
261
|
+
out.add(base)
|
|
262
|
+
out.add(`${base}e`)
|
|
263
|
+
if (/([b-df-hj-np-tv-z])\1$/.test(base)) out.add(base.slice(0, -1))
|
|
264
|
+
}
|
|
265
|
+
return [...out]
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** The first token that is a write verb in any form, or a conjunction; null when there is none. */
|
|
269
|
+
function writeToken(name) {
|
|
270
|
+
for (const token of tokens(name)) {
|
|
271
|
+
if (CONJUNCTIONS.includes(token)) return { token, conjunction: true }
|
|
272
|
+
const verb = stems(token).find((form) => WRITE_VERBS.includes(form))
|
|
273
|
+
if (verb) return { token, verb }
|
|
274
|
+
}
|
|
275
|
+
return null
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
function writeReason(found, where = "") {
|
|
279
|
+
return found.conjunction ? `"${found.token}"${where} joins two actions in one name` : `"${found.token}"${where} is a write verb (${found.verb})`
|
|
280
|
+
}
|
|
281
|
+
|
|
282
|
+
/**
|
|
283
|
+
* Why a grant is refused, or null when it is inside the frame (§5.6).
|
|
284
|
+
*
|
|
285
|
+
* - `action` is `<ns>_<tail>` or `<ns>.<tail>`; a tail starting `<ns>_` (an
|
|
286
|
+
* MCP server of the same name) loses that prefix once.
|
|
287
|
+
* - The tail is `events_list`; or `read` with a `[{account}:]<op>` resource
|
|
288
|
+
* whose op's last dotted segment starts with a read verb; or a tail whose
|
|
289
|
+
* first `_` token is a read verb.
|
|
290
|
+
* - Every token of the tail, and of a `read` op, passes the write-verb check.
|
|
291
|
+
* - No `*` or `?` in an action; a resource is `*` or a template whose only
|
|
292
|
+
* placeholder is `{account}`.
|
|
293
|
+
*
|
|
294
|
+
* @param {unknown} grant
|
|
295
|
+
* @param {string} namespace
|
|
296
|
+
* @returns {string | null}
|
|
297
|
+
*/
|
|
298
|
+
export function checkGrant(grant, namespace) {
|
|
299
|
+
if (!isObject(grant)) return "a grant must be an object {action, resource}"
|
|
300
|
+
for (const key of Object.keys(grant)) if (key !== "action" && key !== "resource") return `a grant has an extra field ${echo(key)}`
|
|
301
|
+
const { action, resource } = grant
|
|
302
|
+
if (typeof action !== "string" || action.length === 0 || action.length > 120) return "a grant's action must be text of at most 120 characters"
|
|
303
|
+
const name = echo(action)
|
|
304
|
+
if (typeof resource !== "string" || resource.length === 0 || resource.length > 200) return `${name}: the resource must be text of at most 200 characters`
|
|
305
|
+
if (/[*?]/.test(action)) return `${name}: an action may not hold * or ?`
|
|
306
|
+
if (!/^[A-Za-z0-9_.-]+$/.test(action)) return `${name}: an action is letters, digits, _, . and - only`
|
|
307
|
+
const placeholders = resource.match(/\{[^}]*\}?/g) ?? []
|
|
308
|
+
if (placeholders.some((item) => item !== "{account}") || /[{}]/.test(resource.replaceAll("{account}", ""))) return `${name}: a resource's only placeholder is {account}`
|
|
309
|
+
if (resource !== "*" && resource.includes("*")) return `${name}: a resource is * or a template, not a pattern`
|
|
310
|
+
let tail = null
|
|
311
|
+
for (const separator of ["_", "."]) if (action.startsWith(`${namespace}${separator}`)) tail = action.slice(namespace.length + 1)
|
|
312
|
+
if (tail === null) return `${name}: not in the namespace ${namespace}`
|
|
313
|
+
if (tail.startsWith(`${namespace}_`)) tail = tail.slice(namespace.length + 1)
|
|
314
|
+
if (tail === "") return `${name}: no tool name after the namespace`
|
|
315
|
+
const write = writeToken(tail)
|
|
316
|
+
if (write) return `${name}: ${writeReason(write)}`
|
|
317
|
+
if (tail === "events_list") return null
|
|
318
|
+
if (tail === "read") {
|
|
319
|
+
const op = resource.startsWith("{account}:") ? resource.slice("{account}:".length) : resource
|
|
320
|
+
if (!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(op)) return `${name}: a read resource is [{account}:]<op>, a dotted operation name`
|
|
321
|
+
const opWrite = writeToken(op)
|
|
322
|
+
if (opWrite) return `${name}: ${writeReason(opWrite, ` in ${echo(op)}`)}`
|
|
323
|
+
const first = tokens(op.split(".").at(-1))[0]
|
|
324
|
+
if (!READ_VERBS.includes(first)) return `${name}: ${echo(op)} does not start with a read verb (${READ_VERBS.join(", ")})`
|
|
325
|
+
return null
|
|
326
|
+
}
|
|
327
|
+
const first = tail.split("_")[0]
|
|
328
|
+
if (!READ_VERBS.includes(first)) return `${name}: "${echo(first)}" is not a read verb (${READ_VERBS.join(", ")})`
|
|
329
|
+
return null
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
function grants(value, namespace, where) {
|
|
333
|
+
list(value, where, { min: 0, max: MAX_GRANTS })
|
|
334
|
+
if (value.length > MAX_GRANTS) fail(`${where}: at most ${MAX_GRANTS} grants`)
|
|
335
|
+
const seen = new Set()
|
|
336
|
+
for (const grant of value) {
|
|
337
|
+
const reason = checkGrant(grant, namespace)
|
|
338
|
+
if (reason) fail(`${where}: ${reason}`)
|
|
339
|
+
const key = `${grant.action}\u0000${grant.resource}`
|
|
340
|
+
if (seen.has(key)) fail(`${where}: ${grant.action} is listed twice`)
|
|
341
|
+
seen.add(key)
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
/**
|
|
346
|
+
* A v2 grant (§9.1 A and D): `<ns>_<tool>` or `<ns>.<verb>`, a read verb
|
|
347
|
+
* somewhere in the name and no write verb anywhere, and a resource of `*` or
|
|
348
|
+
* `{account}:<operation>` whose last dotted segment starts with a read verb —
|
|
349
|
+
* an allowlist, so an operation added to an API later is refused by default.
|
|
350
|
+
*/
|
|
351
|
+
function connectorGrants(value, namespace, where) {
|
|
352
|
+
list(value, where, { min: 1, max: MAX_GRANTS })
|
|
353
|
+
const seen = new Set()
|
|
354
|
+
for (const grant of value) {
|
|
355
|
+
object(grant, where)
|
|
356
|
+
only(grant, ["action", "resource"], where)
|
|
357
|
+
const { action, resource } = grant
|
|
358
|
+
if (typeof action !== "string" || action.length === 0 || action.length > 120) fail(`${where}: an action must be text of at most 120 characters`)
|
|
359
|
+
const name = echo(action)
|
|
360
|
+
if (typeof resource !== "string" || resource.length === 0 || resource.length > 200) fail(`${where}: ${name}: the resource must be text of at most 200 characters`)
|
|
361
|
+
if (/[*?]/.test(action) || !/^[A-Za-z0-9_.-]+$/.test(action)) fail(`${where}: ${name}: an action is letters, digits, _, . and - only, with no * or ?`)
|
|
362
|
+
const write = writeToken(action)
|
|
363
|
+
if (write) fail(`${where}: ${name}: ${writeReason(write)}`)
|
|
364
|
+
if (!tokens(action).some((token) => READ_VERBS.includes(token))) fail(`${where}: ${name} has no read verb (${READ_VERBS.join(", ")})`)
|
|
365
|
+
if (!action.startsWith(`${namespace}_`) && !action.startsWith(`${namespace}.`)) fail(`${where}: ${name} is not in the namespace ${namespace}`)
|
|
366
|
+
const placeholders = resource.match(/\{[^}]*\}?/g) ?? []
|
|
367
|
+
if (placeholders.some((item) => item !== "{account}") || /[{}]/.test(resource.replaceAll("{account}", ""))) fail(`${where}: ${name}: a resource's only placeholder is {account}`)
|
|
368
|
+
if (resource !== "*" && resource.includes("*")) fail(`${where}: ${name}: a resource is * or a template, not a pattern`)
|
|
369
|
+
if (resource !== "*") {
|
|
370
|
+
const operation = resource.startsWith("{account}:") ? resource.slice("{account}:".length) : resource
|
|
371
|
+
if (!/^[A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z][A-Za-z0-9]*)*$/.test(operation)) fail(`${where}: ${name}: a read resource is {account}:<operation>, a dotted operation name`)
|
|
372
|
+
const last = operation.split(".").at(-1)
|
|
373
|
+
if (!READ_VERBS.some((verb) => tokens(last)[0]?.startsWith(verb) ?? last.startsWith(verb))) fail(`${where}: ${name}: ${echo(last)} does not start with a read verb (${READ_VERBS.join(", ")})`)
|
|
374
|
+
}
|
|
375
|
+
const key = `${action}\u0000${resource}`
|
|
376
|
+
if (seen.has(key)) fail(`${where}: ${action} is listed twice`)
|
|
377
|
+
seen.add(key)
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
|
|
381
|
+
function checkSource(source, namespace, at) {
|
|
382
|
+
object(source, at)
|
|
383
|
+
only(source, ["id", "title", "summary", "contract", "input", "kinds", "grants", "probe", "scope", "cadence", "billing", "setup"], at)
|
|
384
|
+
const id = pattern(source.id, ID, `${at}.id`)
|
|
385
|
+
const where = `source ${id}`
|
|
386
|
+
text(source.title, `${where}: title`, { max: 60 })
|
|
387
|
+
text(source.summary, `${where}: summary`, { max: 200 })
|
|
388
|
+
if (source.contract !== SOURCE_CONTRACT) fail(`${where}: contract must be ${SOURCE_CONTRACT} (events_list v2)`)
|
|
389
|
+
if (source.input !== undefined) {
|
|
390
|
+
object(source.input, `${where}: input`)
|
|
391
|
+
if (Buffer.byteLength(canonicalJSON(source.input)) > MAX_INPUT_BYTES) fail(`${where}: input is larger than ${MAX_INPUT_BYTES} bytes`)
|
|
392
|
+
}
|
|
393
|
+
list(source.kinds, `${where}: kinds`, { min: 1, max: EVENT_KINDS.length })
|
|
394
|
+
if (!source.kinds.every((kind) => EVENT_KINDS.includes(kind)) || new Set(source.kinds).size !== source.kinds.length) fail(`${where}: kinds must be distinct names from ${EVENT_KINDS.join(", ")}`)
|
|
395
|
+
if (!Array.isArray(source.grants) || source.grants.length === 0) fail(`${where}: grants must list the actions events_list asserts`)
|
|
396
|
+
if (source.grants.length > MAX_GRANTS) fail(`${where}: at most ${MAX_GRANTS} grants`)
|
|
397
|
+
grants(source.grants, namespace, `${where}: grants`)
|
|
398
|
+
if (source.probe !== undefined) {
|
|
399
|
+
object(source.probe, `${where}: probe`)
|
|
400
|
+
only(source.probe, ["grants"], `${where}: probe`)
|
|
401
|
+
if (source.probe.grants !== undefined) {
|
|
402
|
+
if (Array.isArray(source.probe.grants) && source.probe.grants.length > MAX_GRANTS) fail(`${where}: probe: at most ${MAX_GRANTS} grants`)
|
|
403
|
+
grants(source.probe.grants, namespace, `${where}: probe.grants`)
|
|
404
|
+
}
|
|
405
|
+
}
|
|
406
|
+
if (source.scope !== undefined) {
|
|
407
|
+
list(source.scope, `${where}: scope`, { max: MAX_SCOPE_KEYS })
|
|
408
|
+
const keys = new Set()
|
|
409
|
+
for (const [index, item] of source.scope.entries()) {
|
|
410
|
+
const at2 = `${where}: scope[${index}]`
|
|
411
|
+
object(item, at2)
|
|
412
|
+
only(item, ["key", "title", "kind", "pattern", "max", "required", "suggest"], at2)
|
|
413
|
+
const key = pattern(item.key, /^[a-z][a-z0-9_]{0,31}$/, `${at2}.key`)
|
|
414
|
+
if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
|
|
415
|
+
keys.add(key)
|
|
416
|
+
text(item.title, `${at2}.title`, { max: 60 })
|
|
417
|
+
if (item.kind !== "ids") fail(`${at2}.kind must be "ids"`)
|
|
418
|
+
if (typeof item.pattern !== "string" || item.pattern.length === 0 || item.pattern.length > 120) fail(`${at2}.pattern must be a regular expression of at most 120 characters`)
|
|
419
|
+
try {
|
|
420
|
+
new RegExp(item.pattern, "u")
|
|
421
|
+
} catch {
|
|
422
|
+
fail(`${at2}.pattern is not a valid regular expression`)
|
|
423
|
+
}
|
|
424
|
+
integer(item.max, `${at2}.max`, { min: 1, max: 64 })
|
|
425
|
+
bool(item.required, `${at2}.required`)
|
|
426
|
+
bool(item.suggest, `${at2}.suggest`)
|
|
427
|
+
}
|
|
428
|
+
}
|
|
429
|
+
if (source.cadence !== undefined) {
|
|
430
|
+
object(source.cadence, `${where}: cadence`)
|
|
431
|
+
only(source.cadence, ["everyMinutes"], `${where}: cadence`)
|
|
432
|
+
// Memory clamps it to at least 15 (120 when billed) at use; here it is only a number.
|
|
433
|
+
integer(source.cadence.everyMinutes, `${where}: cadence.everyMinutes`, { min: 1, max: 10_080 })
|
|
434
|
+
}
|
|
435
|
+
if (source.billing !== undefined && source.billing !== null) {
|
|
436
|
+
object(source.billing, `${where}: billing`)
|
|
437
|
+
only(source.billing, ["unit", "note"], `${where}: billing`)
|
|
438
|
+
if (source.billing.unit !== "call") fail(`${where}: billing.unit must be "call"`)
|
|
439
|
+
if (source.billing.note !== undefined) text(source.billing.note, `${where}: billing.note`, { max: 200 })
|
|
440
|
+
}
|
|
441
|
+
if (source.setup !== undefined) text(source.setup, `${where}: setup`, { max: 300, empty: true })
|
|
442
|
+
return id
|
|
443
|
+
}
|
|
444
|
+
|
|
445
|
+
/**
|
|
446
|
+
* The markup a template's literal text may not carry: the block's own markers
|
|
447
|
+
* (a `<!-- /lens -->` in a line would end the block early), an image or a link
|
|
448
|
+
* (a line is text), an HTML tag, and a heading or quote (a line starts with the
|
|
449
|
+
* block's own bullet).
|
|
450
|
+
*/
|
|
451
|
+
const LINE_MARKUP = Object.freeze([
|
|
452
|
+
[/<!--|-->/, "an HTML comment, or a lens marker"],
|
|
453
|
+
[/!\[/, "an image"],
|
|
454
|
+
[/\]\(/, "a link"],
|
|
455
|
+
[/<\/?[a-z]/i, "an HTML tag"],
|
|
456
|
+
[/^\s*#{1,6}\s/, "a heading"],
|
|
457
|
+
[/^\s*>\s/, "a quote"],
|
|
458
|
+
])
|
|
459
|
+
|
|
460
|
+
/**
|
|
461
|
+
* Why a text carries markup a line may not have, or null. One judgement, used
|
|
462
|
+
* on a template's literal text and again on the line **after** substitution:
|
|
463
|
+
* a placeholder's value is collected text, so markup can arrive through it.
|
|
464
|
+
*/
|
|
465
|
+
export function lineMarkupProblem(value) {
|
|
466
|
+
const text = String(value ?? "")
|
|
467
|
+
for (const [pattern, what] of LINE_MARKUP) if (pattern.test(text)) return what
|
|
468
|
+
return null
|
|
469
|
+
}
|
|
470
|
+
|
|
471
|
+
/** The characters that turn two placeholders into markup: `!{title}({url})`. */
|
|
472
|
+
const MARKUP_NEIGHBOURS = new Set(["!", "[", "]", "(", ")"])
|
|
473
|
+
|
|
474
|
+
/** A render line's literal text, with its placeholders checked and cut out, and no markup left in it. */
|
|
475
|
+
function renderLine(line, where) {
|
|
476
|
+
text(line, where, { max: 200 })
|
|
477
|
+
// A placeholder may not sit against the characters that make markup: the
|
|
478
|
+
// rendered line is checked too, but a template that can build markup at all
|
|
479
|
+
// is refused before it ever runs.
|
|
480
|
+
for (const match of line.matchAll(/\{([^{}]*)\}/g)) {
|
|
481
|
+
const name = match[1]
|
|
482
|
+
const before = match.index > 0 ? line[match.index - 1] : ""
|
|
483
|
+
const after = line[match.index + match[0].length] ?? ""
|
|
484
|
+
for (const [side, neighbour] of [["before", before], ["after", after]]) {
|
|
485
|
+
if (MARKUP_NEIGHBOURS.has(neighbour)) fail(`${where}: the placeholder {${echo(name)}} sits next to "${neighbour}" (${side} it), which makes markup. Put a space between them`)
|
|
486
|
+
}
|
|
487
|
+
}
|
|
488
|
+
const literal = line.replace(/\{([^{}]*)\}/g, (_, name) => {
|
|
489
|
+
if (RENDER_PLACEHOLDERS.includes(name)) return " "
|
|
490
|
+
if (/^metric:/.test(name) && METRIC.test(name.slice("metric:".length))) return " "
|
|
491
|
+
fail(`${where}: {${echo(name)}} is not a placeholder (${RENDER_PLACEHOLDERS.map((p) => `{${p}}`).join(", ")}, {metric:<key>})`)
|
|
492
|
+
})
|
|
493
|
+
if (/[{}]/.test(literal)) fail(`${where}: an unmatched { or }`)
|
|
494
|
+
const markup = lineMarkupProblem(literal)
|
|
495
|
+
if (markup) fail(`${where} carries markup: ${markup}. A line is text; the block's markers are Memory's`)
|
|
496
|
+
text(literal, where, { max: 200, empty: true })
|
|
497
|
+
}
|
|
498
|
+
|
|
499
|
+
function checkOutput(output, engine, where) {
|
|
500
|
+
if (typeof output !== "string") fail(`${where}: an output must be text`)
|
|
501
|
+
if (output === "journal" || output === "timeline") return
|
|
502
|
+
if (output.startsWith("section:")) {
|
|
503
|
+
if (engine !== "render") fail(`${where}: a section output is for the render engine only`)
|
|
504
|
+
text(output.slice("section:".length), `${where}: the section heading`, { max: 60 })
|
|
505
|
+
return
|
|
506
|
+
}
|
|
507
|
+
if (output.startsWith("proposal:") && PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) {
|
|
508
|
+
if (engine !== "extract") fail(`${where}: proposals come from the extract engine only`)
|
|
509
|
+
return
|
|
510
|
+
}
|
|
511
|
+
fail(`${where}: ${echo(output)} is not an output kind (journal, timeline, section:<Heading>, proposal:${PROPOSAL_OUTPUTS.join("|")})`)
|
|
512
|
+
}
|
|
513
|
+
|
|
514
|
+
function checkRoutine(routine, sources, at) {
|
|
515
|
+
object(routine, at)
|
|
516
|
+
only(routine, ["id", "title", "summary", "on", "engine", "select", "hints", "render", "outputs", "budget"], at)
|
|
517
|
+
const id = pattern(routine.id, ID, `${at}.id`)
|
|
518
|
+
const where = `routine ${id}`
|
|
519
|
+
text(routine.title, `${where}: title`, { max: 60 })
|
|
520
|
+
text(routine.summary, `${where}: summary`, { max: 200 })
|
|
521
|
+
if (!CADENCES.includes(routine.on)) fail(`${where}: on must be ${CADENCES.join(", ")}`)
|
|
522
|
+
if (!ENGINES.includes(routine.engine)) fail(`${where}: engine must be render or extract`)
|
|
523
|
+
const select = object(routine.select, `${where}: select`)
|
|
524
|
+
only(select, ["sources", "kinds", "labels", "unit", "participant", "latest", "window", "minEvents", "maxUnits"], `${where}: select`)
|
|
525
|
+
list(select.sources, `${where}: select.sources`, { min: 1, max: MAX_SOURCES })
|
|
526
|
+
for (const name of select.sources) if (typeof name !== "string" || !sources.has(name)) fail(`${where}: select.sources may name only this plugin's own sources`)
|
|
527
|
+
if (select.kinds !== undefined) {
|
|
528
|
+
const allowed = new Set(select.sources.flatMap((name) => sources.get(name)))
|
|
529
|
+
list(select.kinds, `${where}: select.kinds`, { min: 1, max: EVENT_KINDS.length })
|
|
530
|
+
if (!select.kinds.every((kind) => allowed.has(kind))) fail(`${where}: select.kinds must be kinds its sources declare`)
|
|
531
|
+
}
|
|
532
|
+
if (select.labels !== undefined) {
|
|
533
|
+
list(select.labels, `${where}: select.labels`, { min: 1, max: 16 })
|
|
534
|
+
for (const label of select.labels) pattern(label, LABEL, `${where}: a label`)
|
|
535
|
+
}
|
|
536
|
+
if (!UNITS.includes(select.unit)) fail(`${where}: select.unit must be event or thread`)
|
|
537
|
+
if (select.participant !== undefined && select.participant !== "owner") fail(`${where}: select.participant may only be "owner"`)
|
|
538
|
+
if (select.latest !== undefined) {
|
|
539
|
+
object(select.latest, `${where}: select.latest`)
|
|
540
|
+
only(select.latest, ["per"], `${where}: select.latest`)
|
|
541
|
+
pattern(select.latest.per, LABEL_PREFIX, `${where}: select.latest.per`)
|
|
542
|
+
}
|
|
543
|
+
if (!WINDOWS.includes(select.window)) fail(`${where}: select.window must be ${WINDOWS.join(", ")}`)
|
|
544
|
+
if (select.minEvents !== undefined) integer(select.minEvents, `${where}: select.minEvents`, { min: 1, max: 1000 })
|
|
545
|
+
if (select.maxUnits !== undefined) integer(select.maxUnits, `${where}: select.maxUnits`, { min: 1, max: 200 })
|
|
546
|
+
if (routine.engine === "extract") {
|
|
547
|
+
if (routine.render !== undefined) fail(`${where}: render is for the render engine only`)
|
|
548
|
+
if (routine.hints !== undefined) text(routine.hints, `${where}: hints`, { max: MAX_HINTS })
|
|
549
|
+
if (routine.budget !== undefined) {
|
|
550
|
+
object(routine.budget, `${where}: budget`)
|
|
551
|
+
only(routine.budget, ["tokensPerRun"], `${where}: budget`)
|
|
552
|
+
// Clamped to MAX_TOKENS_PER_RUN at use (§4.6); here only a positive number.
|
|
553
|
+
integer(routine.budget.tokensPerRun, `${where}: budget.tokensPerRun`, { min: 1, max: 1_000_000 })
|
|
554
|
+
}
|
|
555
|
+
} else {
|
|
556
|
+
if (routine.hints !== undefined) fail(`${where}: hints are for the extract engine only`)
|
|
557
|
+
if (routine.budget !== undefined) fail(`${where}: a budget is for the extract engine only`)
|
|
558
|
+
const render = object(routine.render, `${where}: render`)
|
|
559
|
+
only(render, ["into", "heading", "line", "max"], `${where}: render`)
|
|
560
|
+
if (render.into !== "journal" && render.into !== "section") fail(`${where}: render.into must be journal or section`)
|
|
561
|
+
text(render.heading, `${where}: render.heading`, { max: 60 })
|
|
562
|
+
renderLine(render.line, `${where}: render.line`)
|
|
563
|
+
integer(render.max, `${where}: render.max`, { min: 1, max: MAX_RENDER_ITEMS })
|
|
564
|
+
}
|
|
565
|
+
list(routine.outputs, `${where}: outputs`, { min: 1, max: 12 })
|
|
566
|
+
if (new Set(routine.outputs).size !== routine.outputs.length) fail(`${where}: an output is listed twice`)
|
|
567
|
+
for (const output of routine.outputs) checkOutput(output, routine.engine, `${where}: outputs`)
|
|
568
|
+
return id
|
|
569
|
+
}
|
|
570
|
+
|
|
571
|
+
/**
|
|
572
|
+
* Validate a `package.json#memory` value against `memory-plugin.v2` (or v1, the
|
|
573
|
+
* schema before connectors) and the frame. Never throws.
|
|
574
|
+
*
|
|
575
|
+
* @param {unknown} value
|
|
576
|
+
* @returns {{ ok: true, errors: [], reason: null, namespace: string } | { ok: false, errors: string[], reason: string }}
|
|
577
|
+
*/
|
|
578
|
+
export function validateManifest(value) {
|
|
579
|
+
try {
|
|
580
|
+
const manifest = object(value, "the memory section")
|
|
581
|
+
if (deeperThan(manifest, MAX_DEPTH)) fail(`the memory section is nested deeper than ${MAX_DEPTH} levels`)
|
|
582
|
+
if (!Number.isInteger(manifest.version) || !SCHEMA_VERSIONS.includes(manifest.version)) fail(`version must be ${SCHEMA_VERSIONS.join(" or ")} (memory-plugin.v${SCHEMA_VERSION})`)
|
|
583
|
+
const namespace = manifest.version === 1 ? checkManifestV1(manifest) : checkManifestV2(manifest)
|
|
584
|
+
canonicalJSON(manifest)
|
|
585
|
+
return { ok: true, errors: [], reason: null, namespace }
|
|
586
|
+
} catch (error) {
|
|
587
|
+
const reason = error instanceof Invalid ? error.message : "the memory section could not be read"
|
|
588
|
+
return { ok: false, errors: [reason.slice(0, 300)], reason: reason.slice(0, 300) }
|
|
589
|
+
}
|
|
590
|
+
}
|
|
591
|
+
|
|
592
|
+
/** v1: sources of events and routines over them. Kept while a v1 plugin is installed. */
|
|
593
|
+
function checkManifestV1(manifest) {
|
|
594
|
+
only(manifest, ["$schema", "version", "namespace", "sources", "routines"], "the memory section")
|
|
595
|
+
if (manifest.$schema !== undefined && (typeof manifest.$schema !== "string" || manifest.$schema.length > 300)) fail("$schema must be a URL of at most 300 characters")
|
|
596
|
+
const namespace = namespaceOf(manifest)
|
|
597
|
+
list(manifest.sources, "sources", { min: 1, max: MAX_SOURCES })
|
|
598
|
+
const sources = new Map()
|
|
599
|
+
for (const [index, source] of manifest.sources.entries()) {
|
|
600
|
+
const id = checkSource(source, namespace, `sources[${index}]`)
|
|
601
|
+
if (sources.has(id)) fail(`duplicate source id ${id}`)
|
|
602
|
+
sources.set(id, source.kinds)
|
|
603
|
+
}
|
|
604
|
+
if (manifest.routines !== undefined) {
|
|
605
|
+
list(manifest.routines, "routines", { max: MAX_ROUTINES })
|
|
606
|
+
const ids = new Set()
|
|
607
|
+
for (const [index, routine] of manifest.routines.entries()) {
|
|
608
|
+
const id = checkRoutine(routine, sources, `routines[${index}]`)
|
|
609
|
+
if (ids.has(id)) fail(`duplicate routine id ${id}`)
|
|
610
|
+
ids.add(id)
|
|
611
|
+
}
|
|
612
|
+
}
|
|
613
|
+
return namespace
|
|
614
|
+
}
|
|
615
|
+
|
|
616
|
+
/** The namespace both schemas share, reserved names refused. */
|
|
617
|
+
function namespaceOf(manifest) {
|
|
618
|
+
const namespace = pattern(manifest.namespace, NAMESPACE, "namespace")
|
|
619
|
+
if (RESERVED_NAMESPACES.includes(namespace)) fail(`namespace ${namespace} is reserved`)
|
|
620
|
+
return namespace
|
|
621
|
+
}
|
|
622
|
+
|
|
623
|
+
// ---------------------------------------------------------------------------
|
|
624
|
+
// v2 (§9): the connector, its sources' identities, its reads, and its templates
|
|
625
|
+
|
|
626
|
+
/** A v2 section key the schema does not define, with the rename the design made where there is one. */
|
|
627
|
+
function onlyV2(value, keys, where) {
|
|
628
|
+
for (const key of Object.keys(value)) {
|
|
629
|
+
if (keys.includes(key)) continue
|
|
630
|
+
fail(key === "setup" ? `${where} has the unknown field setup: the static line is setupHint (§9.2)` : `${where} has an unknown field ${echo(key)}`)
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
|
|
634
|
+
function checkManifestV2(manifest) {
|
|
635
|
+
only(manifest, ["$schema", "version", "namespace", "connector", "sources", "templates"], "the memory section")
|
|
636
|
+
if (typeof manifest.$schema !== "string" || manifest.$schema.length > 300) fail("$schema must be a URL of at most 300 characters")
|
|
637
|
+
const namespace = namespaceOf(manifest)
|
|
638
|
+
const connector = checkConnector(manifest.connector, namespace)
|
|
639
|
+
list(manifest.sources, "sources", { min: 1, max: MAX_SOURCES })
|
|
640
|
+
const sources = new Map()
|
|
641
|
+
for (const [index, source] of manifest.sources.entries()) {
|
|
642
|
+
const id = checkConnectorSource(source, namespace, connector, `sources[${index}]`)
|
|
643
|
+
if (sources.has(id)) fail(`duplicate source id ${id}`)
|
|
644
|
+
sources.set(id, source)
|
|
645
|
+
}
|
|
646
|
+
// §9.1 D: a source's grants are a job's grants, so a suggestBy grant that is one
|
|
647
|
+
// of them has entered a job by the back door.
|
|
648
|
+
for (const source of sources.values()) {
|
|
649
|
+
for (const grant of source.grants) {
|
|
650
|
+
if (connector.suggest.has(grant.action)) fail(`source ${source.id}: ${grant.action} is a suggestBy grant and also a source's grant: suggestBy runs only at bind, so it is never a job's (§9.1 D)`)
|
|
651
|
+
}
|
|
652
|
+
}
|
|
653
|
+
// §9.2: a connector-wide default identity is enough until one sign-in differs;
|
|
654
|
+
// a source with none of its own needs the connector's.
|
|
655
|
+
if (!connector.identity && ![...sources.values()].every((source) => source.identity)) {
|
|
656
|
+
fail(`a source declares no identity and the connector has none, so Memory cannot read which account it is (§9.2)`)
|
|
657
|
+
}
|
|
658
|
+
if (manifest.templates !== undefined) {
|
|
659
|
+
list(manifest.templates, "templates", { max: MAX_TEMPLATES })
|
|
660
|
+
const ids = new Set()
|
|
661
|
+
for (const [index, template] of manifest.templates.entries()) {
|
|
662
|
+
const id = checkTemplate(template, new Set(sources.keys()), `templates[${index}]`, connector.reads)
|
|
663
|
+
if (ids.has(id)) fail(`duplicate template id ${id}`)
|
|
664
|
+
ids.add(id)
|
|
665
|
+
}
|
|
666
|
+
}
|
|
667
|
+
return namespace
|
|
668
|
+
}
|
|
669
|
+
|
|
670
|
+
/**
|
|
671
|
+
* §9.1 B and D: the connector's accounts, its own scope keys with their
|
|
672
|
+
* `suggestBy`, its declared reads, and whether it claims `operationScoped`.
|
|
673
|
+
*/
|
|
674
|
+
function checkConnector(connector, namespace) {
|
|
675
|
+
object(connector, "the connector")
|
|
676
|
+
onlyV2(connector, ["accounts", "identity", "identityRead", "operationScoped", "reads", "scope", "billing", "urlHosts"], "the connector")
|
|
677
|
+
if (connector.accounts !== "single" && connector.accounts !== "multi") fail(`connector.accounts must be "single" or "multi"`)
|
|
678
|
+
if (connector.operationScoped !== undefined) bool(connector.operationScoped, "connector.operationScoped")
|
|
679
|
+
if (connector.identity !== undefined) checkIdentity(connector.identity, namespace, "the connector's identity", { sourceLevel: true })
|
|
680
|
+
if (connector.identityRead !== undefined) checkIdentity(connector.identityRead, namespace, "the connector's identityRead", { sourceLevel: false })
|
|
681
|
+
const scopeKeys = checkScope(connector.scope, namespace, "the connector's scope")
|
|
682
|
+
const reads = checkReads(connector.reads, namespace, scopeKeys)
|
|
683
|
+
// §9.1 B: `operationScoped` is a claim Memory can check and acts on: every
|
|
684
|
+
// dotted action's grant names its operation, so a job may call a direct read.
|
|
685
|
+
if (connector.operationScoped === true) {
|
|
686
|
+
const dotted = [...reads.values()].flatMap((read) => read.grants).filter((grant) => grant.action.includes("."))
|
|
687
|
+
if (dotted.length === 0) fail("connector.operationScoped is true, but no read declares a dotted action with an operation resource")
|
|
688
|
+
for (const grant of dotted) if (grant.resource === "*") fail(`connector.operationScoped is true, so ${grant.action} must name {account}:<operation>, not "*"`)
|
|
689
|
+
}
|
|
690
|
+
if (connector.billing !== undefined && connector.billing !== null) billing(connector.billing, "connector.billing")
|
|
691
|
+
// §9.4: the hosts a templated `{url}` may point at. A destination is a
|
|
692
|
+
// security decision, so a connector declares its own and nothing else renders.
|
|
693
|
+
const urlHosts = []
|
|
694
|
+
if (connector.urlHosts !== undefined) {
|
|
695
|
+
list(connector.urlHosts, "connector.urlHosts", { max: 8 })
|
|
696
|
+
for (const host of connector.urlHosts) {
|
|
697
|
+
const problem = urlHostProblem(host)
|
|
698
|
+
if (problem) fail(`connector.urlHosts: ${echo(host)} ${problem}`)
|
|
699
|
+
urlHosts.push(host.toLowerCase())
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
// §9.1 D: a suggestBy read runs only at bind, so its grants must never be a
|
|
703
|
+
// job-bearing grant: no identity, no identityRead, and no declared read.
|
|
704
|
+
const suggest = (Array.isArray(connector.scope) ? connector.scope : []).flatMap((key) => (Array.isArray(key?.suggestBy?.grants) ? key.suggestBy.grants : [])).map((grant) => grant.action)
|
|
705
|
+
const bearing = new Set([connector.identity, connector.identityRead, ...(Array.isArray(connector.reads) ? connector.reads : [])]
|
|
706
|
+
.flatMap((block) => (Array.isArray(block?.grants) ? block.grants : []))
|
|
707
|
+
.map((grant) => grant.action))
|
|
708
|
+
for (const action of new Set(suggest)) if (bearing.has(action)) fail(`${action} is a suggestBy grant and also a job-bearing grant: suggestBy runs only at bind, so its grants must not appear in an identity, identityRead or read (§9.1 D)`)
|
|
709
|
+
return { identity: connector.identity, identityRead: connector.identityRead, scopeKeys, reads, suggest: new Set(suggest), urlHosts }
|
|
710
|
+
}
|
|
711
|
+
|
|
712
|
+
/** §9.2: an identity answers the account and the owner, and nothing else. */
|
|
713
|
+
function checkIdentity(identity, namespace, where, { sourceLevel }) {
|
|
714
|
+
object(identity, where)
|
|
715
|
+
onlyV2(identity, ["method", "input", "grants", "account", "owner"], where)
|
|
716
|
+
if (sourceLevel) {
|
|
717
|
+
if (identity.method !== "events_list") fail(`${where}: method must be events_list: a source's identity is its limit:0 call (§9.2)`)
|
|
718
|
+
if (identity.input !== undefined) {
|
|
719
|
+
object(identity.input, `${where}: input`)
|
|
720
|
+
for (const key of Object.keys(identity.input)) if (!["source", "account", "limit"].includes(key)) fail(`${where}: input may name only source, account and limit`)
|
|
721
|
+
if (identity.input.limit !== 0) fail(`${where}: input.limit must be 0: the identity is the owner-only call, and any other limit reads events`)
|
|
722
|
+
}
|
|
723
|
+
if (Object.keys(identity.input ?? {}).length === 0) fail(`${where}: input must name the source and limit 0`)
|
|
724
|
+
} else {
|
|
725
|
+
if (typeof identity.method !== "string" || identity.method === "events_list") fail(`${where}: method must name the tools RPC read that answers the account (§9.2)`)
|
|
726
|
+
readName(identity.method, `${where}: method`)
|
|
727
|
+
}
|
|
728
|
+
connectorGrants(identity.grants, namespace, `${where}: grants`)
|
|
729
|
+
if (typeof identity.account !== "string" || !identity.account.startsWith("$.")) fail(`${where}: account must be a JSONPath starting $.`)
|
|
730
|
+
object(identity.owner, `${where}: owner`)
|
|
731
|
+
only(identity.owner, ["id", "label"], `${where}: owner`)
|
|
732
|
+
for (const key of ["id", "label"]) if (typeof identity.owner[key] !== "string" || !identity.owner[key].startsWith("$.")) fail(`${where}: owner.${key} must be a JSONPath starting $.`)
|
|
733
|
+
}
|
|
734
|
+
|
|
735
|
+
/** A read's method name: the verb allowlist, and no write verb anywhere (§9.1 A). */
|
|
736
|
+
function readName(name, where) {
|
|
737
|
+
if (typeof name !== "string" || name.length === 0 || name.length > 120) fail(`${where} must be a name of at most 120 characters`)
|
|
738
|
+
const write = writeToken(name)
|
|
739
|
+
if (write) fail(`${where}: ${writeReason(write)}`)
|
|
740
|
+
if (!tokens(name).some((token) => READ_VERBS.includes(token))) fail(`${where}: "${echo(name)}" has no read verb (${READ_VERBS.join(", ")})`)
|
|
741
|
+
}
|
|
742
|
+
|
|
743
|
+
/**
|
|
744
|
+
* §9.1 C: a scope key is what the person confirms. `suggestBy` runs only at
|
|
745
|
+
* bind, so its grants are checked like any other read's and kept out of jobs.
|
|
746
|
+
*/
|
|
747
|
+
function checkScope(scope, namespace, where) {
|
|
748
|
+
if (!Array.isArray(scope)) fail(`${where} must be a list, empty when none`)
|
|
749
|
+
list(scope, where, { max: MAX_SCOPE_KEYS })
|
|
750
|
+
const keys = new Set()
|
|
751
|
+
for (const [index, entry] of scope.entries()) {
|
|
752
|
+
const at = `${where}[${index}]`
|
|
753
|
+
object(entry, at)
|
|
754
|
+
onlyV2(entry, ["key", "title", "kind", "pattern", "max", "required", "suggest", "suggestBy"], at)
|
|
755
|
+
const key = pattern(entry.key, /^[a-z][a-z0-9_]{0,31}$/, `${at}.key`)
|
|
756
|
+
if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
|
|
757
|
+
keys.add(key)
|
|
758
|
+
if (entry.title !== undefined) text(entry.title, `${at}.title`, { max: 60 })
|
|
759
|
+
if (entry.kind !== "ids") fail(`${at}.kind must be "ids"`)
|
|
760
|
+
if (typeof entry.pattern !== "string" || entry.pattern.length === 0 || entry.pattern.length > 120) fail(`${at}.pattern must be a regular expression of at most 120 characters`)
|
|
761
|
+
try {
|
|
762
|
+
new RegExp(entry.pattern, "u")
|
|
763
|
+
} catch {
|
|
764
|
+
fail(`${at}.pattern is not a valid regular expression`)
|
|
765
|
+
}
|
|
766
|
+
integer(entry.max, `${at}.max`, { min: 1, max: 64 })
|
|
767
|
+
bool(entry.required, `${at}.required`)
|
|
768
|
+
if (entry.suggest !== undefined) bool(entry.suggest, `${at}.suggest`)
|
|
769
|
+
if (entry.suggest === true && entry.suggestBy === undefined) fail(`${at} claims suggest: true but declares no suggestBy, so Memory has nothing to call`)
|
|
770
|
+
if (entry.suggestBy !== undefined) {
|
|
771
|
+
object(entry.suggestBy, `${at}.suggestBy`)
|
|
772
|
+
onlyV2(entry.suggestBy, ["method", "input", "grants", "ids", "labels"], `${at}.suggestBy`)
|
|
773
|
+
readName(entry.suggestBy.method, `${at}.suggestBy.method`)
|
|
774
|
+
if (entry.suggestBy.input !== undefined) object(entry.suggestBy.input, `${at}.suggestBy.input`)
|
|
775
|
+
connectorGrants(entry.suggestBy.grants, namespace, `${at}.suggestBy: grants`)
|
|
776
|
+
for (const field of ["ids", "labels"]) {
|
|
777
|
+
if (entry.suggestBy[field] !== undefined && (typeof entry.suggestBy[field] !== "string" || !entry.suggestBy[field].startsWith("$."))) fail(`${at}.suggestBy.${field} must be a JSONPath starting $.`)
|
|
778
|
+
}
|
|
779
|
+
}
|
|
780
|
+
}
|
|
781
|
+
return keys
|
|
782
|
+
}
|
|
783
|
+
|
|
784
|
+
/** §9.1 B and C: each declared read, its grants, and the scope inputs that pin it. */
|
|
785
|
+
function checkReads(reads, namespace, scopeKeys) {
|
|
786
|
+
const byMethod = new Map()
|
|
787
|
+
if (reads === undefined) return byMethod
|
|
788
|
+
list(reads, "connector.reads", { max: MAX_READS })
|
|
789
|
+
for (const [index, read] of reads.entries()) {
|
|
790
|
+
const at = `connector.reads[${index}]`
|
|
791
|
+
object(read, at)
|
|
792
|
+
onlyV2(read, ["method", "input", "grants", "scopeInputs", "kinds", "cursor", "billing"], at)
|
|
793
|
+
readName(read.method, `${at}.method`)
|
|
794
|
+
if (byMethod.has(read.method)) fail(`${at}.method ${echo(read.method)} is declared twice`)
|
|
795
|
+
if (read.input !== undefined) {
|
|
796
|
+
object(read.input, `${at}.input`)
|
|
797
|
+
if (Buffer.byteLength(canonicalJSON(read.input)) > MAX_INPUT_BYTES) fail(`${at}: input is larger than ${MAX_INPUT_BYTES} bytes`)
|
|
798
|
+
}
|
|
799
|
+
connectorGrants(read.grants, namespace, `${at}: grants`)
|
|
800
|
+
checkScopeInputs(read.scopeInputs, `${at}.scopeInputs`, scopeKeys)
|
|
801
|
+
if (read.kinds !== undefined) {
|
|
802
|
+
list(read.kinds, `${at}.kinds`, { min: 1, max: EVENT_KINDS.length })
|
|
803
|
+
if (!read.kinds.every((kind) => EVENT_KINDS.includes(kind))) fail(`${at}.kinds must be names from ${EVENT_KINDS.join(", ")}`)
|
|
804
|
+
}
|
|
805
|
+
if (read.cursor !== undefined) text(read.cursor, `${at}.cursor`, { max: 60 })
|
|
806
|
+
if (read.billing !== undefined && read.billing !== null) billing(read.billing, `${at}.billing`)
|
|
807
|
+
byMethod.set(read.method, read)
|
|
808
|
+
}
|
|
809
|
+
return byMethod
|
|
810
|
+
}
|
|
811
|
+
|
|
812
|
+
/**
|
|
813
|
+
* §9.1 C, as the kit checks it: a read is pinned to the confirmed scope by at
|
|
814
|
+
* least one binding-key input; a `perUnit` input takes its value from the event
|
|
815
|
+
* itself, and every `perUnit` of one read shares one `bind`; a `thread_ts`
|
|
816
|
+
* needs its `thread_channel` on the same bind, so a thread's channel is what
|
|
817
|
+
* keeps it inside the confirmed scope.
|
|
818
|
+
*/
|
|
819
|
+
function checkScopeInputs(inputs, where, scopeKeys) {
|
|
820
|
+
if (inputs === undefined) fail(`${where} is missing: a read with no scope input is unscoped and not grantable`)
|
|
821
|
+
object(inputs, where)
|
|
822
|
+
if (Object.keys(inputs).length === 0) fail(`${where} is empty: a read with no scope input is unscoped and not grantable`)
|
|
823
|
+
let bound = 0
|
|
824
|
+
const binds = new Set()
|
|
825
|
+
const perUnit = []
|
|
826
|
+
for (const [field, value] of Object.entries(inputs)) {
|
|
827
|
+
if (typeof value === "string") {
|
|
828
|
+
if (!scopeKeys.has(value)) fail(`${where}.${field} names the scope key "${echo(value)}", which the connector's scope does not declare`)
|
|
829
|
+
bound += 1
|
|
830
|
+
continue
|
|
831
|
+
}
|
|
832
|
+
object(value, `${where}.${field}`)
|
|
833
|
+
onlyV2(value, ["perUnit", "bind"], `${where}.${field}`)
|
|
834
|
+
if (!PER_UNIT_FIELDS.includes(value.perUnit)) fail(`${where}.${field}: perUnit must be one of ${PER_UNIT_FIELDS.join(", ")} (a field of the event shape)`)
|
|
835
|
+
if (typeof value.bind !== "string" || !scopeKeys.has(value.bind)) fail(`${where}.${field}: perUnit needs bind to name a declared scope key, so the id stays inside the confirmed scope`)
|
|
836
|
+
binds.add(value.bind)
|
|
837
|
+
perUnit.push([field, value])
|
|
838
|
+
}
|
|
839
|
+
// §9.1 C: external_id is a per-unit value like any other, but it names no
|
|
840
|
+
// conversation: a read pinned only by it is pinned by nothing.
|
|
841
|
+
if (perUnit.length > 0 && perUnit.every(([, value]) => value.perUnit === "external_id")) fail(`${where} is pinned only by external_id, which names no conversation: a read needs a confirmed scope key (§9.1 C)`)
|
|
842
|
+
const ts = perUnit.find(([, value]) => value.perUnit === "thread_ts")
|
|
843
|
+
if (ts && !perUnit.some(([, value]) => value.perUnit === "thread_channel" && value.bind === ts[1].bind)) {
|
|
844
|
+
fail(`${where}.${ts[0]}: a thread_ts needs a thread_channel input on the same bind, so the thread's channel is pinned to the confirmed scope`)
|
|
845
|
+
}
|
|
846
|
+
if (binds.size > 1) fail(`${where} binds per-unit inputs to ${[...binds].join(", ")}: they must all name one scope key`)
|
|
847
|
+
if (bound === 0 && binds.size === 0) fail(`${where} pins no binding-key input, so the read is not scoped to what the person confirmed`)
|
|
848
|
+
if (bound > 0 && binds.size > 0) {
|
|
849
|
+
for (const key of binds) {
|
|
850
|
+
if (!Object.values(inputs).includes(key)) fail(`${where} pins a per-unit input through the unrelated key ${key}: its bind must be one of this read's binding-key inputs`)
|
|
851
|
+
}
|
|
852
|
+
}
|
|
853
|
+
}
|
|
854
|
+
|
|
855
|
+
/** §9.2: a source's grants are exactly what `events_list` asserts; its identity's are among them. */
|
|
856
|
+
function checkConnectorSource(source, namespace, connector, at) {
|
|
857
|
+
object(source, at)
|
|
858
|
+
onlyV2(source, ["id", "title", "summary", "contract", "input", "kinds", "grants", "identity", "scope", "cadence", "billing", "setupHint"], at)
|
|
859
|
+
const id = pattern(source.id, ID, `${at}.id`)
|
|
860
|
+
const where = `source ${id}`
|
|
861
|
+
text(source.title, `${where}: title`, { max: 60 })
|
|
862
|
+
text(source.summary, `${where}: summary`, { max: 200 })
|
|
863
|
+
if (source.contract !== SOURCE_CONTRACT) fail(`${where}: contract must be ${SOURCE_CONTRACT} (events_list v2)`)
|
|
864
|
+
if (source.input !== undefined) {
|
|
865
|
+
object(source.input, `${where}: input`)
|
|
866
|
+
if (Buffer.byteLength(canonicalJSON(source.input)) > MAX_INPUT_BYTES) fail(`${where}: input is larger than ${MAX_INPUT_BYTES} bytes`)
|
|
867
|
+
}
|
|
868
|
+
list(source.kinds, `${where}: kinds`, { min: 1, max: EVENT_KINDS.length })
|
|
869
|
+
if (!source.kinds.every((kind) => EVENT_KINDS.includes(kind)) || new Set(source.kinds).size !== source.kinds.length) fail(`${where}: kinds must be distinct names from ${EVENT_KINDS.join(", ")}`)
|
|
870
|
+
if (!Array.isArray(source.grants) || source.grants.length === 0) fail(`${where}: grants must list the actions events_list asserts`)
|
|
871
|
+
connectorGrants(source.grants, namespace, `${where}: grants`)
|
|
872
|
+
if (source.identity !== undefined) {
|
|
873
|
+
checkIdentity(source.identity, namespace, `${where}: identity`, { sourceLevel: true })
|
|
874
|
+
}
|
|
875
|
+
// §9.1 D: an identity's grants are only what `limit: 0` asserts, and they must
|
|
876
|
+
// be among the source's — that list is what a job's session allows for it.
|
|
877
|
+
const identity = source.identity ?? connector.identity
|
|
878
|
+
if (identity) {
|
|
879
|
+
const listed = new Set(source.grants.map((grant) => `${grant.action}\u0000${grant.resource}`))
|
|
880
|
+
for (const grant of identity.grants) {
|
|
881
|
+
if (!listed.has(`${grant.action}\u0000${grant.resource}`)) fail(`${where}: identity grants ${grant.action} on ${grant.resource}, which ${where}: grants does not list — an identity's grants must be among the source's (§9.1 D)`)
|
|
882
|
+
}
|
|
883
|
+
}
|
|
884
|
+
if (source.scope !== undefined) {
|
|
885
|
+
list(source.scope, `${where}: scope`, { max: MAX_SCOPE_KEYS })
|
|
886
|
+
const keys = new Set()
|
|
887
|
+
for (const [index, item] of source.scope.entries()) {
|
|
888
|
+
const at2 = `${where}: scope[${index}]`
|
|
889
|
+
object(item, at2)
|
|
890
|
+
onlyV2(item, ["key", "title", "kind", "pattern", "max", "required", "suggest"], at2)
|
|
891
|
+
const key = pattern(item.key, /^[a-z][a-z0-9_]{0,31}$/, `${at2}.key`)
|
|
892
|
+
if (keys.has(key)) fail(`${where}: scope key ${key} is listed twice`)
|
|
893
|
+
keys.add(key)
|
|
894
|
+
if (!connector.scopeKeys.has(key)) fail(`${at2} names ${key}, which the connector's scope does not declare`)
|
|
895
|
+
}
|
|
896
|
+
}
|
|
897
|
+
if (source.cadence !== undefined) {
|
|
898
|
+
object(source.cadence, `${where}: cadence`)
|
|
899
|
+
only(source.cadence, ["everyMinutes"], `${where}: cadence`)
|
|
900
|
+
// Memory clamps it to at least 15 (120 when billed) at use; here it is only a number.
|
|
901
|
+
integer(source.cadence.everyMinutes, `${where}: cadence.everyMinutes`, { min: 1, max: 10_080 })
|
|
902
|
+
}
|
|
903
|
+
if (source.billing !== undefined && source.billing !== null) billing(source.billing, `${where}: billing`)
|
|
904
|
+
if (source.setupHint !== undefined) text(source.setupHint, `${where}: setupHint`, { max: 300, empty: true })
|
|
905
|
+
return id
|
|
906
|
+
}
|
|
907
|
+
|
|
908
|
+
function billing(value, where) {
|
|
909
|
+
object(value, where)
|
|
910
|
+
only(value, ["unit", "note"], where)
|
|
911
|
+
if (value.unit !== "call") fail(`${where}.unit must be "call"`)
|
|
912
|
+
if (value.note !== undefined) text(value.note, `${where}.note`, { max: 200 })
|
|
913
|
+
}
|
|
914
|
+
|
|
915
|
+
/**
|
|
916
|
+
* §9.4: a template is a draft job a person can instantiate. It carries no
|
|
917
|
+
* grants and no account, so it can never widen what the person confirmed.
|
|
918
|
+
*/
|
|
919
|
+
function checkTemplate(template, sourceIds, at, reads = new Map()) {
|
|
920
|
+
object(template, at)
|
|
921
|
+
onlyV2(template, ["id", "title", "summary", "trigger", "extract", "transform", "curate", "outputs", "budget"], at)
|
|
922
|
+
const id = pattern(template.id, ID, `${at}.id`)
|
|
923
|
+
const where = `template ${id}`
|
|
924
|
+
text(template.title, `${where}: title`, { max: 60 })
|
|
925
|
+
text(template.summary, `${where}: summary`, { max: 200 })
|
|
926
|
+
if (template.trigger !== undefined) {
|
|
927
|
+
object(template.trigger, `${where}: trigger`)
|
|
928
|
+
only(template.trigger, ["schedule"], `${where}: trigger`)
|
|
929
|
+
object(template.trigger.schedule, `${where}: trigger.schedule`)
|
|
930
|
+
only(template.trigger.schedule, ["every", "cron", "tz"], `${where}: trigger.schedule`)
|
|
931
|
+
if (template.trigger.schedule.every !== undefined) pattern(template.trigger.schedule.every, /^[0-9]{1,4}(m|h|d)$/, `${where}: trigger.schedule.every`)
|
|
932
|
+
if (template.trigger.schedule.cron !== undefined) text(template.trigger.schedule.cron, `${where}: trigger.schedule.cron`, { max: 120 })
|
|
933
|
+
if (template.trigger.schedule.tz !== undefined) text(template.trigger.schedule.tz, `${where}: trigger.schedule.tz`, { max: 64 })
|
|
934
|
+
}
|
|
935
|
+
const extract = object(template.extract, `${where}: extract`)
|
|
936
|
+
only(extract, ["steps"], `${where}: extract`)
|
|
937
|
+
const steps = list(extract.steps, `${where}: extract.steps`, { min: 1, max: 8 })
|
|
938
|
+
for (const [index, step] of steps.entries()) {
|
|
939
|
+
const at2 = `${where}: extract.steps[${index}]`
|
|
940
|
+
object(step, at2)
|
|
941
|
+
onlyV2(step, ["use", "call", "connector", "source", "for", "with", "paginate", "cursor", "emit"], at2)
|
|
942
|
+
const byUse = step.use !== undefined
|
|
943
|
+
const byCall = typeof step.call === "string"
|
|
944
|
+
if (byUse === byCall) fail(`${at2} needs exactly one of use (events_list) and call`)
|
|
945
|
+
if (byUse && step.use !== "events_list") fail(`${at2}.use must be events_list`)
|
|
946
|
+
if (byCall) readName(step.call, `${at2}.call`)
|
|
947
|
+
pattern(step.connector, /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/, `${at2}.connector`)
|
|
948
|
+
if (typeof step.source !== "string" || !sourceIds.has(step.source)) fail(`${at2}.source must name one of this plugin's declared sources`)
|
|
949
|
+
if (step.for !== undefined && step.for !== "thread" && step.for !== "unit") fail(`${at2}.for must be "thread" or "unit"`)
|
|
950
|
+
if (step.with !== undefined) {
|
|
951
|
+
object(step.with, `${at2}.with`)
|
|
952
|
+
// §9.1 C: the read pins these itself, from the person's confirmed scope.
|
|
953
|
+
// A template that set one would replace the pin, so it may not.
|
|
954
|
+
const pinned = new Set(Object.keys(byCall ? reads.get(step.call)?.scopeInputs ?? {} : {}))
|
|
955
|
+
for (const key of Object.keys(step.with)) {
|
|
956
|
+
if (pinned.has(key)) fail(`${at2}.with may not set ${echo(key)}: the read pins it from the person's confirmed scope, and a template cannot replace that (§9.1 C)`)
|
|
957
|
+
}
|
|
958
|
+
// §2.2: a step's inputs are binding values only, never an event's text.
|
|
959
|
+
for (const match of JSON.stringify(step.with).matchAll(/\{\{([^}]+)\}\}/g)) {
|
|
960
|
+
const ref = match[1].trim()
|
|
961
|
+
if (!/^(account|since|cursor\.[a-z][a-z0-9_]*|scope\.[a-z][a-z0-9_]*)$/.test(ref)) fail(`${at2}.with uses {{${echo(ref)}}}: only binding values are allowed, never item text`)
|
|
962
|
+
}
|
|
963
|
+
}
|
|
964
|
+
}
|
|
965
|
+
if (template.transform !== undefined) {
|
|
966
|
+
object(template.transform, `${where}: transform`)
|
|
967
|
+
only(template.transform, ["into", "map"], `${where}: transform`)
|
|
968
|
+
if (template.transform.into !== "events" && template.transform.into !== "documents") fail(`${where}: transform.into must be events or documents`)
|
|
969
|
+
if (template.transform.map !== undefined) object(template.transform.map, `${where}: transform.map`)
|
|
970
|
+
}
|
|
971
|
+
const curate = object(template.curate, `${where}: curate`)
|
|
972
|
+
only(curate, ["stages"], `${where}: curate`)
|
|
973
|
+
const stages = list(curate.stages, `${where}: curate.stages`, { min: 1, max: 8 })
|
|
974
|
+
const written = []
|
|
975
|
+
for (const [index, stage] of stages.entries()) {
|
|
976
|
+
const at2 = `${where}: curate.stages[${index}]`
|
|
977
|
+
object(stage, at2)
|
|
978
|
+
onlyV2(stage, ["engine", "select", "into", "heading", "line", "max", "hints", "outputs"], at2)
|
|
979
|
+
if (stage.engine !== "render" && stage.engine !== "extract" && stage.engine !== "synthesize") fail(`${at2}.engine must be render, extract or synthesize`)
|
|
980
|
+
if (stage.engine === "render") {
|
|
981
|
+
const into = stage.into
|
|
982
|
+
const isSection = typeof into === "string" && /^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(into)
|
|
983
|
+
if (!isSection && into !== "journal" && into !== "timeline") fail(`${at2}.into must be journal, timeline or section:<Heading>`)
|
|
984
|
+
if (typeof stage.line !== "string" || stage.line.length === 0 || stage.line.length > 400) fail(`${at2}.line must be 1 to 400 characters`)
|
|
985
|
+
renderLine(stage.line, `${at2}.line`)
|
|
986
|
+
integer(stage.max, `${at2}.max`, { min: 1, max: MAX_RENDER_ITEMS })
|
|
987
|
+
if (stage.heading !== undefined) text(stage.heading, `${at2}.heading`, { max: 60 })
|
|
988
|
+
if (stage.outputs !== undefined) fail(`${at2}: a render stage's output is its into`)
|
|
989
|
+
written.push(into)
|
|
990
|
+
}
|
|
991
|
+
if (stage.engine === "extract") {
|
|
992
|
+
const outputs = list(stage.outputs, `${at2}.outputs`, { min: 1, max: 12 })
|
|
993
|
+
for (const output of outputs) {
|
|
994
|
+
if (!output.startsWith("proposal:") || !PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) fail(`${at2}.outputs names ${echo(output)}, which is not a proposal kind`)
|
|
995
|
+
written.push(output)
|
|
996
|
+
}
|
|
997
|
+
if (stage.hints !== undefined) text(stage.hints, `${at2}.hints`, { max: MAX_HINTS })
|
|
998
|
+
if (stage.into !== undefined || stage.line !== undefined) fail(`${at2}: an extract stage takes outputs and hints, not into or line`)
|
|
999
|
+
}
|
|
1000
|
+
if (stage.engine === "synthesize") {
|
|
1001
|
+
if (typeof stage.into !== "string" || !/^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(stage.into)) fail(`${at2}.into must be section:<Heading>`)
|
|
1002
|
+
integer(stage.max, `${at2}.max`, { min: 1, max: MAX_RENDER_ITEMS })
|
|
1003
|
+
written.push(stage.into)
|
|
1004
|
+
}
|
|
1005
|
+
if (stage.select !== undefined) checkSelector(stage.select, sourceIds, `${at2}.select`)
|
|
1006
|
+
}
|
|
1007
|
+
const outputs = list(template.outputs, `${where}: outputs`, { min: 1, max: 12 })
|
|
1008
|
+
if (new Set(outputs).size !== outputs.length) fail(`${where}: an output is listed twice`)
|
|
1009
|
+
for (const output of outputs) {
|
|
1010
|
+
if (output === "journal" || output === "timeline") continue
|
|
1011
|
+
if (typeof output === "string" && /^section:[A-Z][A-Za-z0-9 ]{0,39}$/.test(output)) continue
|
|
1012
|
+
if (typeof output === "string" && output.startsWith("proposal:") && PROPOSAL_OUTPUTS.includes(output.slice("proposal:".length))) continue
|
|
1013
|
+
fail(`${where}: outputs names ${echo(output)}, which is not an output kind`)
|
|
1014
|
+
}
|
|
1015
|
+
// §9.1 D: a template's outputs cover every stage's, or a stage would write what
|
|
1016
|
+
// the person never saw in the draft.
|
|
1017
|
+
for (const output of new Set(written)) if (!outputs.includes(output)) fail(`${where}: outputs must include ${echo(output)}, which a stage writes`)
|
|
1018
|
+
if (template.budget !== undefined) {
|
|
1019
|
+
object(template.budget, `${where}: budget`)
|
|
1020
|
+
only(template.budget, ["tokensPerRun"], `${where}: budget`)
|
|
1021
|
+
integer(template.budget.tokensPerRun, `${where}: budget.tokensPerRun`, { min: 1000, max: MAX_TOKENS_PER_RUN })
|
|
1022
|
+
}
|
|
1023
|
+
return id
|
|
1024
|
+
}
|
|
1025
|
+
|
|
1026
|
+
/** The selector a stage reads units with (§9.4). */
|
|
1027
|
+
function checkSelector(select, sourceIds, where) {
|
|
1028
|
+
object(select, where)
|
|
1029
|
+
only(select, ["sources", "kinds", "labels", "unit", "participant", "latest", "window", "minEvents", "maxUnits"], where)
|
|
1030
|
+
if (select.sources !== undefined) {
|
|
1031
|
+
list(select.sources, `${where}.sources`, { min: 1, max: MAX_SOURCES })
|
|
1032
|
+
for (const name of select.sources) if (typeof name !== "string" || !sourceIds.has(name)) fail(`${where}.sources may name only this plugin's own sources`)
|
|
1033
|
+
}
|
|
1034
|
+
if (select.kinds !== undefined) {
|
|
1035
|
+
list(select.kinds, `${where}.kinds`, { min: 1, max: EVENT_KINDS.length })
|
|
1036
|
+
if (!select.kinds.every((kind) => EVENT_KINDS.includes(kind))) fail(`${where}.kinds must be event kinds`)
|
|
1037
|
+
}
|
|
1038
|
+
if (select.labels !== undefined) {
|
|
1039
|
+
list(select.labels, `${where}.labels`, { min: 1, max: 16 })
|
|
1040
|
+
for (const label of select.labels) pattern(label, LABEL, `${where}: a label`)
|
|
1041
|
+
}
|
|
1042
|
+
if (select.unit !== undefined && !UNITS.includes(select.unit)) fail(`${where}.unit must be event or thread`)
|
|
1043
|
+
if (select.participant !== undefined && select.participant !== "owner") fail(`${where}.participant may only be "owner"`)
|
|
1044
|
+
if (select.latest !== undefined) {
|
|
1045
|
+
object(select.latest, `${where}.latest`)
|
|
1046
|
+
only(select.latest, ["per"], `${where}.latest`)
|
|
1047
|
+
pattern(select.latest.per, LABEL_PREFIX, `${where}.latest.per`)
|
|
1048
|
+
}
|
|
1049
|
+
if (select.window !== undefined && !WINDOWS.includes(select.window)) fail(`${where}.window must be ${WINDOWS.join(", ")}`)
|
|
1050
|
+
if (select.minEvents !== undefined) integer(select.minEvents, `${where}.minEvents`, { min: 1, max: 1000 })
|
|
1051
|
+
if (select.maxUnits !== undefined) integer(select.maxUnits, `${where}.maxUnits`, { min: 1, max: 200 })
|
|
1052
|
+
}
|
|
1053
|
+
|
|
1054
|
+
// ---------------------------------------------------------------------------
|
|
1055
|
+
// What a job reads: the identity, the declared reads, the templates, and the
|
|
1056
|
+
// exact grant set of §9.1 D
|
|
1057
|
+
|
|
1058
|
+
/** The identity a source reads its account and owner with: its own, else the connector's (§9.2). */
|
|
1059
|
+
export function identityFor(manifest, sourceId) {
|
|
1060
|
+
const source = (manifest?.sources ?? []).find((entry) => entry?.id === sourceId) ?? null
|
|
1061
|
+
if (!source) return null
|
|
1062
|
+
return source.identity ?? manifest?.connector?.identity ?? null
|
|
1063
|
+
}
|
|
1064
|
+
|
|
1065
|
+
/** Every read the connector declares, by method. */
|
|
1066
|
+
export function declaredReads(manifest) {
|
|
1067
|
+
return Array.isArray(manifest?.connector?.reads) ? manifest.connector.reads : []
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
/** One declared read, or null when the connector declares none with that method. */
|
|
1071
|
+
export function readByMethod(manifest, method) {
|
|
1072
|
+
return declaredReads(manifest).find((read) => read?.method === method) ?? null
|
|
1073
|
+
}
|
|
1074
|
+
|
|
1075
|
+
/** The templates a manifest ships (§9.4). */
|
|
1076
|
+
export function templatesOf(manifest) {
|
|
1077
|
+
return Array.isArray(manifest?.templates) ? manifest.templates : []
|
|
1078
|
+
}
|
|
1079
|
+
|
|
1080
|
+
/** The template with this id, or null. */
|
|
1081
|
+
export function templateById(manifest, id) {
|
|
1082
|
+
return templatesOf(manifest).find((template) => template?.id === id) ?? null
|
|
1083
|
+
}
|
|
1084
|
+
|
|
1085
|
+
/** An account name a grant's resource may bind to. A wildcard, separator or empty is never one. */
|
|
1086
|
+
export function accountName(value) {
|
|
1087
|
+
if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._@%+-]{0,127}$/.test(value)) throw new TypeError("an account must be a plain account name")
|
|
1088
|
+
return value
|
|
1089
|
+
}
|
|
1090
|
+
|
|
1091
|
+
/**
|
|
1092
|
+
* The exact grant set a running job holds (DESIGN §9.1 D): every grant of the
|
|
1093
|
+
* job's source, every grant of each read its steps name, and every grant of the
|
|
1094
|
+
* identity's owner-only call, with `{account}` bound.
|
|
1095
|
+
*
|
|
1096
|
+
* `suggestBy` is not in it, and can never be: it runs only at bind, in the probe
|
|
1097
|
+
* session. A read the job's steps do not name contributes no grant.
|
|
1098
|
+
*
|
|
1099
|
+
* @param {any} manifest
|
|
1100
|
+
* @param {{source: string, account: string, steps?: Array<{use?: string, call?: string}>}} input
|
|
1101
|
+
* @returns {Array<{action: string, resource: string}>}
|
|
1102
|
+
*/
|
|
1103
|
+
export function jobGrants(manifest, { source: sourceId, account, steps = [] }) {
|
|
1104
|
+
const source = (manifest?.sources ?? []).find((entry) => entry?.id === sourceId)
|
|
1105
|
+
if (!source) throw new TypeError(`the declaration has no source ${String(sourceId)}`)
|
|
1106
|
+
const bound = accountName(account)
|
|
1107
|
+
const out = new Map()
|
|
1108
|
+
const add = (grant) => {
|
|
1109
|
+
if (!grant || typeof grant.action !== "string" || typeof grant.resource !== "string") return
|
|
1110
|
+
const resource = grant.resource.replaceAll("{account}", bound)
|
|
1111
|
+
out.set(`${grant.action}\u0000${resource}`, { action: grant.action, resource })
|
|
1112
|
+
}
|
|
1113
|
+
for (const grant of Array.isArray(source.grants) ? source.grants : []) add(grant)
|
|
1114
|
+
for (const step of Array.isArray(steps) ? steps : []) {
|
|
1115
|
+
if (typeof step?.call !== "string") continue
|
|
1116
|
+
const read = readByMethod(manifest, step.call)
|
|
1117
|
+
if (!read) throw new TypeError(`the job's step calls ${String(step.call)}, which the declaration does not declare`)
|
|
1118
|
+
for (const grant of Array.isArray(read.grants) ? read.grants : []) add(grant)
|
|
1119
|
+
}
|
|
1120
|
+
const identity = identityFor(manifest, sourceId)
|
|
1121
|
+
for (const grant of Array.isArray(identity?.grants) ? identity.grants : []) add(grant)
|
|
1122
|
+
return [...out.values()]
|
|
1123
|
+
}
|
|
1124
|
+
|
|
1125
|
+
|
|
1126
|
+
/**
|
|
1127
|
+
* RFC 8785 canonical JSON for the values JSON.parse gives: object keys sorted
|
|
1128
|
+
* by UTF-16 code units, numbers and strings as ECMAScript serialises them.
|
|
1129
|
+
*
|
|
1130
|
+
* @param {unknown} value
|
|
1131
|
+
* @returns {string}
|
|
1132
|
+
*/
|
|
1133
|
+
export function canonicalJSON(value, depth = 0) {
|
|
1134
|
+
if (depth > MAX_CANONICAL_DEPTH) throw new TypeError(`canonical JSON is nested deeper than ${MAX_CANONICAL_DEPTH} levels`)
|
|
1135
|
+
if (value === null || typeof value === "boolean") return JSON.stringify(value)
|
|
1136
|
+
if (typeof value === "number") {
|
|
1137
|
+
if (!Number.isFinite(value)) throw new TypeError("canonical JSON needs finite numbers")
|
|
1138
|
+
return JSON.stringify(value)
|
|
1139
|
+
}
|
|
1140
|
+
if (typeof value === "string") return JSON.stringify(value)
|
|
1141
|
+
if (Array.isArray(value)) return `[${value.map((item) => canonicalJSON(item, depth + 1)).join(",")}]`
|
|
1142
|
+
if (typeof value === "object") {
|
|
1143
|
+
const keys = Object.keys(value).sort()
|
|
1144
|
+
return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalJSON(value[key], depth + 1)}`).join(",")}}`
|
|
1145
|
+
}
|
|
1146
|
+
throw new TypeError(`canonical JSON cannot hold a ${typeof value}`)
|
|
1147
|
+
}
|
|
1148
|
+
|
|
1149
|
+
/** The digest Memory pins a declaration by: `sha256:` and the hex of its canonical JSON. */
|
|
1150
|
+
export function manifestDigest(value) {
|
|
1151
|
+
return `sha256:${createHash("sha256").update(canonicalJSON(value), "utf8").digest("hex")}`
|
|
1152
|
+
}
|
|
1153
|
+
|
|
1154
|
+
/**
|
|
1155
|
+
* A `sources` descriptor's hash: the contract's own (`descriptorHash` in the
|
|
1156
|
+
* source-contract package), which is `manifestDigest` over the same canonical
|
|
1157
|
+
* JSON. Every consumer computes it the same way, so a grant's hash means the
|
|
1158
|
+
* same thing in Memory, jelly and a plugin's CI.
|
|
1159
|
+
*/
|
|
1160
|
+
export function descriptorHash(value) {
|
|
1161
|
+
return manifestDigest(value)
|
|
1162
|
+
}
|