@fungi.computer/oyster 0.10.0 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (107) hide show
  1. package/README.md +103 -12
  2. package/dist/agents.d.ts +66 -22
  3. package/dist/agents.js +128 -38
  4. package/dist/app-builds.d.ts +2 -0
  5. package/dist/app-builds.js +17 -6
  6. package/dist/authorization.d.ts +25 -3
  7. package/dist/authorization.js +47 -14
  8. package/dist/browser/capability-source.d.ts +23 -5
  9. package/dist/browser/capability-source.js +19 -22
  10. package/dist/browser/index.d.ts +2 -1
  11. package/dist/browser/index.js +1 -0
  12. package/dist/browser/live-view.d.ts +38 -0
  13. package/dist/browser/live-view.js +179 -0
  14. package/dist/build/artifact-writer.d.ts +11 -2
  15. package/dist/build/artifact-writer.js +42 -24
  16. package/dist/build/candidate-cli.mjs +26 -18
  17. package/dist/build/content-objects.d.ts +29 -14
  18. package/dist/build/content-objects.js +57 -19
  19. package/dist/build/local-build.js +3 -0
  20. package/dist/build/submission-contract.d.ts +1 -1
  21. package/dist/build/submission-contract.js +5 -5
  22. package/dist/build-egress.d.ts +8 -7
  23. package/dist/build-egress.js +4 -3
  24. package/dist/build.d.ts +1 -1
  25. package/dist/channels/binding.d.ts +2 -0
  26. package/dist/channels/run-decision.d.ts +33 -0
  27. package/dist/channels/run-decision.js +25 -0
  28. package/dist/channels/visitor-channel.d.ts +84 -14
  29. package/dist/channels/visitor-channel.js +55 -32
  30. package/dist/channels/visitor-edge.d.ts +18 -2
  31. package/dist/channels/visitor-edge.js +67 -5
  32. package/dist/channels/visitors.d.ts +4 -0
  33. package/dist/channels/visitors.js +22 -1
  34. package/dist/channels/web-binding.d.ts +117 -0
  35. package/dist/channels/web-binding.js +227 -0
  36. package/dist/embed-metafiles.d.ts +8 -0
  37. package/dist/embed-metafiles.js +2 -0
  38. package/dist/embed-scripts.d.ts +8 -0
  39. package/dist/embed-scripts.js +3 -0
  40. package/dist/host.d.ts +3 -1
  41. package/dist/host.js +6 -1
  42. package/dist/install-release-cli.d.ts +2 -1
  43. package/dist/install-release-cli.js +18 -10
  44. package/dist/installation-client.d.ts +1 -0
  45. package/dist/installation-operations.d.ts +2 -0
  46. package/dist/installation-operations.js +1 -0
  47. package/dist/pack.d.ts +5 -2
  48. package/dist/pack.js +3 -1
  49. package/dist/page/embed-challenge.d.ts +19 -0
  50. package/dist/page/embed-challenge.js +45 -0
  51. package/dist/page/embed-error.d.ts +2 -0
  52. package/dist/page/embed-error.js +16 -0
  53. package/dist/page/embed-loader-protocol.d.ts +12 -0
  54. package/dist/page/embed-loader-protocol.js +29 -0
  55. package/dist/standalone/agent-connections.d.ts +22 -19
  56. package/dist/standalone/agent-connections.js +150 -106
  57. package/dist/standalone/agents.d.ts +174 -16
  58. package/dist/standalone/agents.js +331 -21
  59. package/dist/standalone/browser.d.ts +14 -2
  60. package/dist/standalone/browser.js +52 -4
  61. package/dist/standalone/channel-session-door.d.ts +4 -0
  62. package/dist/standalone/channel-session-door.js +72 -0
  63. package/dist/standalone/computer-egress.d.ts +5 -3
  64. package/dist/standalone/computer-egress.js +1 -1
  65. package/dist/standalone/hello-app.d.ts +9 -0
  66. package/dist/standalone/hello-app.js +78 -0
  67. package/dist/standalone/install-apps-cli.d.ts +2 -1
  68. package/dist/standalone/install-apps-cli.js +36 -14
  69. package/dist/standalone/instance.js +2 -2
  70. package/dist/standalone/local-desktop.d.ts +11 -0
  71. package/dist/standalone/local-desktop.js +75 -0
  72. package/dist/standalone/owner-routes.d.ts +4 -3
  73. package/dist/standalone/owner-routes.js +7 -1
  74. package/dist/standalone/registry.d.ts +2 -0
  75. package/dist/standalone/sign-in-link.d.ts +9 -0
  76. package/dist/standalone/sign-in-link.js +49 -0
  77. package/dist/standalone/try-cli.d.ts +52 -0
  78. package/dist/standalone/try-cli.js +404 -0
  79. package/dist/standalone/visitor-edge.d.ts +36 -0
  80. package/dist/standalone/visitor-edge.js +67 -0
  81. package/dist/standalone/visitor-proof.d.ts +23 -0
  82. package/dist/standalone/visitor-proof.js +67 -0
  83. package/dist/standalone/website-channels.d.ts +134 -0
  84. package/dist/standalone/website-channels.js +262 -0
  85. package/dist/standalone/worker-routes.d.ts +4 -1
  86. package/dist/standalone/worker-routes.js +3 -0
  87. package/dist/standalone/worker.d.ts +2 -1
  88. package/dist/standalone/worker.js +5 -1
  89. package/dist/testing/capabilities.d.ts +3 -0
  90. package/dist/testing/capabilities.js +1 -0
  91. package/dist/testing/installation.d.ts +4 -2
  92. package/dist/testing/installation.js +7 -2
  93. package/dist/webhook-abuse.d.ts +7 -1
  94. package/dist/webhook-abuse.js +8 -2
  95. package/dist/workers-git.js +2 -2
  96. package/dist/workers.d.ts +7 -2
  97. package/dist/workers.js +1 -1
  98. package/docs/api/agents.md +103 -36
  99. package/docs/api/authorization.md +56 -11
  100. package/docs/api/browser.md +115 -8
  101. package/docs/api/build-contract.md +52 -10
  102. package/docs/api/build.md +16 -2
  103. package/docs/api/host.md +1 -0
  104. package/docs/api/pack.md +179 -3
  105. package/docs/api/workers-git.md +6 -6
  106. package/docs/site/agent-quickstart.mdx +8 -0
  107. package/package.json +34 -8
@@ -1,9 +1,11 @@
1
1
  /**
2
- * Oyster's one immutable artifact representation: digest-addressed bytes
2
+ * Oyster's one immutable artifact representation: content-addressed bytes
3
3
  * keyed by artifact reference, with media types carried by the App build
4
- * and asset manifests (never by the store). The local packer writes it to a
5
- * directory, and a host's build owner writes it to that host's artifact store,
6
- * so a Release built on the host and one packed and uploaded share objects.
4
+ * and asset manifests. A build's own objects are named as uploads are
5
+ * (`contentObjectRef`: owner, digest and stored media type); the objects only
6
+ * the store's owner derives are named outside that namespace. The local packer
7
+ * writes it to a directory, and a host's build owner writes it to that host's
8
+ * artifact store under the building Team's or tenant's namespace.
7
9
  *
8
10
  * It has two halves. Staging turns a build's bytes into content-addressed
9
11
  * objects and the output manifest that names them by digest and size. The
@@ -21,11 +23,12 @@ import * as Schema from "effect/Schema";
21
23
  import { assetBuildJsonSchema, assetPathSchema, decodeAssetBuild, } from "@fungi.computer/puffball/assets";
22
24
  import { appBuildJsonSchema, createAppBuild, } from "@fungi.computer/puffball/app";
23
25
  import { parseArtifactRef, parseSha256Digest, } from "@fungi.computer/puffball";
26
+ import { contentObjectRef, } from "./content-objects.js";
24
27
  function sha256(bytes) {
25
28
  return parseSha256Digest(`sha256:${createHash("sha256").update(bytes).digest("hex")}`);
26
29
  }
27
- /** The content address of an object: `artifact:sha256-<hex>`. */
28
- function contentArtifactRef(digest) {
30
+ /** The address of a derived object: `artifact:sha256-<hex>`, which no upload can name. */
31
+ function derivedArtifactRef(digest) {
29
32
  return parseArtifactRef(`artifact:sha256-${digest.slice("sha256:".length)}`);
30
33
  }
31
34
  /**
@@ -40,21 +43,20 @@ const fallbackRootBytes = 1024 * 1024;
40
43
  */
41
44
  export function stageBuildOutput(output) {
42
45
  const objects = [];
43
- const stage = (bytes) => {
46
+ const stage = (bytes, mediaType) => {
44
47
  const digest = sha256(bytes);
45
- if (!objects.some((object) => object.digest === digest))
46
- objects.push({
47
- artifactRef: contentArtifactRef(digest),
48
- bytes: bytes.slice(),
49
- digest,
50
- });
48
+ if (!objects.some((object) => object.digest === digest && object.mediaType === mediaType))
49
+ objects.push({ bytes: bytes.slice(), digest, mediaType });
51
50
  return { digest, byteLength: bytes.byteLength };
52
51
  };
53
52
  const declared = output.declaration === undefined ? {} : { declaration: output.declaration };
54
53
  const ui = (prepared) => prepared.content.kind === "html"
55
54
  ? {
56
55
  mediaType: "text/html; charset=utf-8",
57
- content: { kind: "html", ...stage(prepared.content.bytes) },
56
+ content: {
57
+ kind: "html",
58
+ ...stage(prepared.content.bytes, "text/html; charset=utf-8"),
59
+ },
58
60
  }
59
61
  : {
60
62
  mediaType: "application/vnd.fungi.app-assets+json",
@@ -63,18 +65,22 @@ export function stageBuildOutput(output) {
63
65
  base: prepared.content.base,
64
66
  assets: prepared.content.assets.map((asset) => ({
65
67
  path: asset.path,
66
- ...stage(asset.bytes),
68
+ ...stage(asset.bytes, "application/octet-stream"),
67
69
  })),
68
70
  },
69
71
  };
70
72
  const manifest = output.kind === "ui"
71
73
  ? { kind: "ui", ui: ui(output.ui), ...declared }
72
74
  : output.kind === "backend"
73
- ? { kind: "backend", backend: stage(output.backend), ...declared }
75
+ ? {
76
+ kind: "backend",
77
+ backend: stage(output.backend, "application/vnd.fungi.app-backend+json"),
78
+ ...declared,
79
+ }
74
80
  : {
75
81
  kind: "app",
76
82
  ui: ui(output.ui),
77
- backend: stage(output.backend),
83
+ backend: stage(output.backend, "application/vnd.fungi.app-backend+json"),
78
84
  ...declared,
79
85
  };
80
86
  return { manifest, objects };
@@ -85,15 +91,15 @@ export function stageBuildOutput(output) {
85
91
  */
86
92
  function artifactRootObjects(manifest, options) {
87
93
  const objects = [];
88
- const referenced = (object) => ({
89
- artifactRef: contentArtifactRef(object.digest),
94
+ const referenced = (object, mediaType) => ({
95
+ artifactRef: contentObjectRef(options.owner, object.digest, mediaType),
90
96
  digest: object.digest,
91
97
  version: object.digest,
92
98
  byteLength: object.byteLength,
93
99
  });
94
100
  const stage = (bytes, ref) => {
95
101
  const digest = sha256(bytes);
96
- const artifactRef = ref ?? contentArtifactRef(digest);
102
+ const artifactRef = ref ?? derivedArtifactRef(digest);
97
103
  objects.push({ artifactRef, bytes, digest });
98
104
  return {
99
105
  artifactRef,
@@ -107,7 +113,10 @@ function artifactRootObjects(manifest, options) {
107
113
  if (ui === null)
108
114
  return null;
109
115
  if (ui.content.kind === "html")
110
- return { ...referenced(ui.content), mediaType: ui.mediaType };
116
+ return {
117
+ ...referenced(ui.content, "text/html; charset=utf-8"),
118
+ mediaType: ui.mediaType,
119
+ };
111
120
  if (!options.assetPolicy)
112
121
  throw new Error("Asset writer requires explicit policy");
113
122
  const byPath = new Map();
@@ -125,7 +134,11 @@ function artifactRootObjects(manifest, options) {
125
134
  : mediaType;
126
135
  if (!contentType)
127
136
  throw new Error("Build asset has no maintained content type");
128
- assets.push({ path, ...referenced(asset), contentType });
137
+ assets.push({
138
+ path,
139
+ ...referenced(asset, "application/octet-stream"),
140
+ contentType,
141
+ });
129
142
  }
130
143
  const assetManifest = new TextEncoder().encode(Schema.encodeUnknownSync(assetBuildJsonSchema)({
131
144
  format: "fungi-assets-v1",
@@ -138,7 +151,7 @@ function artifactRootObjects(manifest, options) {
138
151
  const storedBackend = manifest.kind === "ui"
139
152
  ? null
140
153
  : {
141
- ...referenced(manifest.backend),
154
+ ...referenced(manifest.backend, "application/vnd.fungi.app-backend+json"),
142
155
  mediaType: "application/vnd.fungi.app-backend+json",
143
156
  };
144
157
  const rootBytes = new TextEncoder().encode(Schema.encodeUnknownSync(appBuildJsonSchema)(createAppBuild(storedUi, storedBackend, manifest.declaration)));
@@ -176,6 +189,11 @@ export async function writeArtifactRoot(manifest, objects, options) {
176
189
  export async function writeImmutableArtifact(output, objects, options) {
177
190
  const staged = stageBuildOutput(output);
178
191
  const derived = artifactRootObjects(staged.manifest, options);
179
- await storeObjects([...staged.objects, ...derived.objects], objects);
192
+ const owned = staged.objects.map(({ bytes, digest, mediaType }) => ({
193
+ artifactRef: contentObjectRef(options.owner, digest, mediaType),
194
+ bytes,
195
+ digest,
196
+ }));
197
+ await storeObjects([...owned, ...derived.objects], objects);
180
198
  return derived.root;
181
199
  }
@@ -22548,15 +22548,15 @@ function encodeTeamAppCandidateManifest(manifest) {
22548
22548
  function candidateManifestObjects(output) {
22549
22549
  const objects = [];
22550
22550
  const add2 = (object3, mediaType) => {
22551
- const seen = objects.find(({ digest }) => digest === object3.digest);
22552
- if (seen === void 0)
22551
+ const named = objects.filter(({ digest }) => digest === object3.digest);
22552
+ if (named.some(({ byteLength }) => byteLength !== object3.byteLength))
22553
+ throw new Error("One object digest names two sizes");
22554
+ if (!named.some((seen) => seen.mediaType === mediaType))
22553
22555
  objects.push({
22554
22556
  digest: object3.digest,
22555
22557
  byteLength: object3.byteLength,
22556
22558
  mediaType
22557
22559
  });
22558
- else if (seen.byteLength !== object3.byteLength)
22559
- throw new Error("One object digest names two sizes");
22560
22560
  };
22561
22561
  if (output.kind !== "backend") {
22562
22562
  const { content } = output.ui;
@@ -24034,26 +24034,24 @@ function sha256(bytes) {
24034
24034
  `sha256:${createHash2("sha256").update(bytes).digest("hex")}`
24035
24035
  );
24036
24036
  }
24037
- function contentArtifactRef(digest) {
24038
- return parseArtifactRef(`artifact:sha256-${digest.slice("sha256:".length)}`);
24039
- }
24040
24037
  var fallbackRootBytes = 1024 * 1024;
24041
24038
  function stageBuildOutput(output) {
24042
24039
  const objects = [];
24043
- const stage = (bytes) => {
24040
+ const stage = (bytes, mediaType) => {
24044
24041
  const digest = sha256(bytes);
24045
- if (!objects.some((object3) => object3.digest === digest))
24046
- objects.push({
24047
- artifactRef: contentArtifactRef(digest),
24048
- bytes: bytes.slice(),
24049
- digest
24050
- });
24042
+ if (!objects.some(
24043
+ (object3) => object3.digest === digest && object3.mediaType === mediaType
24044
+ ))
24045
+ objects.push({ bytes: bytes.slice(), digest, mediaType });
24051
24046
  return { digest, byteLength: bytes.byteLength };
24052
24047
  };
24053
24048
  const declared = output.declaration === void 0 ? {} : { declaration: output.declaration };
24054
24049
  const ui = (prepared) => prepared.content.kind === "html" ? {
24055
24050
  mediaType: "text/html; charset=utf-8",
24056
- content: { kind: "html", ...stage(prepared.content.bytes) }
24051
+ content: {
24052
+ kind: "html",
24053
+ ...stage(prepared.content.bytes, "text/html; charset=utf-8")
24054
+ }
24057
24055
  } : {
24058
24056
  mediaType: "application/vnd.fungi.app-assets+json",
24059
24057
  content: {
@@ -24061,14 +24059,24 @@ function stageBuildOutput(output) {
24061
24059
  base: prepared.content.base,
24062
24060
  assets: prepared.content.assets.map((asset) => ({
24063
24061
  path: asset.path,
24064
- ...stage(asset.bytes)
24062
+ ...stage(asset.bytes, "application/octet-stream")
24065
24063
  }))
24066
24064
  }
24067
24065
  };
24068
- const manifest = output.kind === "ui" ? { kind: "ui", ui: ui(output.ui), ...declared } : output.kind === "backend" ? { kind: "backend", backend: stage(output.backend), ...declared } : {
24066
+ const manifest = output.kind === "ui" ? { kind: "ui", ui: ui(output.ui), ...declared } : output.kind === "backend" ? {
24067
+ kind: "backend",
24068
+ backend: stage(
24069
+ output.backend,
24070
+ "application/vnd.fungi.app-backend+json"
24071
+ ),
24072
+ ...declared
24073
+ } : {
24069
24074
  kind: "app",
24070
24075
  ui: ui(output.ui),
24071
- backend: stage(output.backend),
24076
+ backend: stage(
24077
+ output.backend,
24078
+ "application/vnd.fungi.app-backend+json"
24079
+ ),
24072
24080
  ...declared
24073
24081
  };
24074
24082
  return { manifest, objects };
@@ -1,9 +1,3 @@
1
- /**
2
- * A build's uploaded objects in an R2-shaped store: content addressed
3
- * (`artifact:sha256-<hex>`), written once from a stream with the store
4
- * itself verifying the digest, and described by `head()` without a read.
5
- * The bytes never pass through an isolate's memory as a whole.
6
- */
7
1
  import { type ArtifactRef, type Sha256Digest } from "@fungi.computer/puffball";
8
2
  import type { ArtifactHead } from "../release.js";
9
3
  import type { CandidateObject, CandidateObjectMediaType } from "./submission-contract.js";
@@ -16,22 +10,43 @@ export type ContentObjectBucket = Readonly<{
16
10
  sha256?: ArrayBuffer;
17
11
  }>;
18
12
  }> | null>;
19
- /** Store `value` at `key`; the bucket refuses bytes whose SHA-256 differs. */
13
+ /**
14
+ * Store `value` at `key`; the bucket refuses bytes whose SHA-256 differs.
15
+ * As in R2, `onlyIf: { etagDoesNotMatch: "*" }` makes the put conditional
16
+ * on `key` being absent: an existing object is kept and the put resolves
17
+ * `null` instead.
18
+ */
20
19
  put(key: string, value: ReadableStream<Uint8Array> | Uint8Array, options: Readonly<{
21
20
  sha256: string;
22
21
  httpMetadata: Readonly<{
23
22
  contentType: CandidateObjectMediaType;
24
23
  }>;
24
+ onlyIf?: Readonly<{
25
+ etagDoesNotMatch: string;
26
+ }>;
25
27
  }>): Promise<object | null>;
26
28
  }>;
27
- /** The store key of one content-addressed object. */
28
- export declare function contentObjectRef(digest: Sha256Digest): ArtifactRef;
29
+ /** The one Team or tenant whose uploads share a key namespace. */
30
+ export type ContentObjectOwner = Readonly<{
31
+ namespace: string;
32
+ }>;
33
+ /**
34
+ * Name the upload namespace of a Team or tenant id. Ids are opaque to the
35
+ * store, so the namespace is a fixed-length digest of the id.
36
+ */
37
+ export declare function contentObjectOwner(id: string): ContentObjectOwner;
38
+ /** The store key of one uploaded object: its owner, digest and stored media type. */
39
+ export declare function contentObjectRef(owner: ContentObjectOwner, digest: Sha256Digest, mediaType: CandidateObjectMediaType): ArtifactRef;
29
40
  /** Describe a stored object by its size and the SHA-256 the store verified. */
30
41
  export declare function headContentObject(bucket: ContentObjectBucket, artifactRef: ArtifactRef): Promise<ArtifactHead | null>;
31
42
  /**
32
- * Stream one object into the store under its digest. The store refuses a
33
- * body whose SHA-256 differs; an object already stored with the same
34
- * verified digest and size is kept (write-once: a stored version may be
35
- * pinned by a Release) and the body is discarded, never stored.
43
+ * Stream one object into the store under its owner, digest and media type. The store refuses a
44
+ * body whose SHA-256 differs. The key is write-once (a stored version may be
45
+ * pinned by a Release): the put is conditional on the key being absent, and
46
+ * an existing object is never replaced. When the key already holds an object
47
+ * of the named size whose store-verified digest is the named one, or that the
48
+ * store never checksummed (a packed upload's plain bytes, which the candidate
49
+ * check reads and hashes), the body is discarded and the object kept; any
50
+ * other existing object refuses the upload.
36
51
  */
37
- export declare function putContentObject(bucket: ContentObjectBucket, object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType): Promise<"stored" | "refused">;
52
+ export declare function putContentObject(bucket: ContentObjectBucket, owner: ContentObjectOwner, object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType): Promise<"stored" | "refused">;
@@ -1,13 +1,41 @@
1
1
  /**
2
- * A build's uploaded objects in an R2-shaped store: content addressed
3
- * (`artifact:sha256-<hex>`), written once from a stream with the store
4
- * itself verifying the digest, and described by `head()` without a read.
5
- * The bytes never pass through an isolate's memory as a whole.
2
+ * A build's uploaded objects in an R2-shaped store: addressed by their owner,
3
+ * content and stored media type (`artifact:o<owner>-sha256-<hex>.<type>`),
4
+ * written once from a stream with the store itself verifying the digest, and
5
+ * described by `head()` without a read. The bytes never pass through an
6
+ * isolate's memory as a whole.
7
+ *
8
+ * The owner (one Team or tenant) is part of the key, so no upload ever leans
9
+ * on an object another owner stored: erasing one owner's Apps cannot take
10
+ * bytes from under another owner's unreleased upload. The media type is part
11
+ * of the key because a reader (the Publisher's) checks the stored type.
12
+ * Objects a host derives itself (asset manifests, roots) are named outside
13
+ * this namespace, so no upload can address them.
6
14
  */
15
+ import { createHash } from "node:crypto";
7
16
  import { parseArtifactRef, parseSha256Digest, } from "@fungi.computer/puffball";
8
- /** The store key of one content-addressed object. */
9
- export function contentObjectRef(digest) {
10
- return parseArtifactRef(`artifact:sha256-${digest.slice("sha256:".length)}`);
17
+ const mediaTypeKeys = {
18
+ "text/html; charset=utf-8": "html",
19
+ "application/vnd.fungi.app-backend+json": "backend",
20
+ "application/octet-stream": "octets",
21
+ };
22
+ /**
23
+ * Name the upload namespace of a Team or tenant id. Ids are opaque to the
24
+ * store, so the namespace is a fixed-length digest of the id.
25
+ */
26
+ export function contentObjectOwner(id) {
27
+ if (id.length === 0)
28
+ throw new Error("Content object owner id is empty");
29
+ return Object.freeze({
30
+ namespace: createHash("sha256")
31
+ .update(`fungi.content-object-owner\0${id}`)
32
+ .digest("hex")
33
+ .slice(0, 32),
34
+ });
35
+ }
36
+ /** The store key of one uploaded object: its owner, digest and stored media type. */
37
+ export function contentObjectRef(owner, digest, mediaType) {
38
+ return parseArtifactRef(`artifact:o${owner.namespace}-sha256-${digest.slice("sha256:".length)}.${mediaTypeKeys[mediaType]}`);
11
39
  }
12
40
  function hex(bytes) {
13
41
  return Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
@@ -24,30 +52,40 @@ export async function headContentObject(bucket, artifactRef) {
24
52
  };
25
53
  }
26
54
  /**
27
- * Stream one object into the store under its digest. The store refuses a
28
- * body whose SHA-256 differs; an object already stored with the same
29
- * verified digest and size is kept (write-once: a stored version may be
30
- * pinned by a Release) and the body is discarded, never stored.
55
+ * Stream one object into the store under its owner, digest and media type. The store refuses a
56
+ * body whose SHA-256 differs. The key is write-once (a stored version may be
57
+ * pinned by a Release): the put is conditional on the key being absent, and
58
+ * an existing object is never replaced. When the key already holds an object
59
+ * of the named size whose store-verified digest is the named one, or that the
60
+ * store never checksummed (a packed upload's plain bytes, which the candidate
61
+ * check reads and hashes), the body is discarded and the object kept; any
62
+ * other existing object refuses the upload.
31
63
  */
32
- export async function putContentObject(bucket, object, body, mediaType) {
33
- const artifactRef = contentObjectRef(object.digest);
64
+ export async function putContentObject(bucket, owner, object, body, mediaType) {
65
+ const artifactRef = contentObjectRef(owner, object.digest, mediaType);
66
+ const kept = (existing) => existing.byteLength === object.byteLength &&
67
+ (existing.digest === null || existing.digest === object.digest);
34
68
  const existing = await headContentObject(bucket, artifactRef);
35
- if (existing !== null &&
36
- existing.digest === object.digest &&
37
- existing.byteLength === object.byteLength) {
69
+ if (existing !== null) {
38
70
  // Read the body through (discarding it) rather than cancel it: a
39
71
  // cancelled request body resets the uploader's connection mid-send.
40
72
  await body?.pipeTo(new WritableStream());
41
- return "stored";
73
+ return kept(existing) ? "stored" : "refused";
42
74
  }
75
+ let written;
43
76
  try {
44
- await bucket.put(artifactRef, body ?? new Uint8Array(0), {
77
+ written = await bucket.put(artifactRef, body ?? new Uint8Array(0), {
45
78
  sha256: object.digest.slice("sha256:".length),
46
79
  httpMetadata: { contentType: mediaType },
80
+ onlyIf: { etagDoesNotMatch: "*" },
47
81
  });
48
82
  }
49
83
  catch {
50
84
  return "refused";
51
85
  }
52
- return "stored";
86
+ if (written !== null)
87
+ return "stored";
88
+ // Another writer took the key after the head above; its object is kept.
89
+ const taken = await headContentObject(bucket, artifactRef);
90
+ return taken !== null && kept(taken) ? "stored" : "refused";
53
91
  }
@@ -10,6 +10,7 @@ function logEvent(operation, cause) {
10
10
  import { frozenSnapshotInstallArguments, packageScriptArguments, } from "./snapshot-package-store.js";
11
11
  import { isInsideSnapshot } from "./snapshot-programs/snapshot-path.js";
12
12
  import { writeImmutableArtifact, } from "./artifact-writer.js";
13
+ import { contentObjectOwner } from "./content-objects.js";
13
14
  import { assetPathSchema, } from "@fungi.computer/puffball/assets";
14
15
  import { appBuildRecipe, readBuildManifest, resolveWorkspaceBuild, workspaceProjectsArguments, } from "./workspace-build.js";
15
16
  import { readBundledHtml } from "./bundled-html.js";
@@ -1109,6 +1110,8 @@ async function writeArtifact(output, artifactRoot, signal, assetPolicy) {
1109
1110
  signal.throwIfAborted();
1110
1111
  await mkdir(artifactRoot, { recursive: true });
1111
1112
  return writeImmutableArtifact(output, directoryArtifactObjects(artifactRoot, signal), {
1113
+ // A local pack is one owner's private directory.
1114
+ owner: contentObjectOwner("local"),
1112
1115
  rootArtifactRef: parseArtifactRef(`artifact:${Buffer.from(randomBytes(16)).toString("hex")}`),
1113
1116
  assetPolicy,
1114
1117
  });
@@ -814,7 +814,7 @@ export declare function candidateObjectMediaType(value: string | null): Candidat
814
814
  export type CandidateUpload = CandidateObject & Readonly<{
815
815
  mediaType: CandidateObjectMediaType;
816
816
  }>;
817
- /** Every distinct object a manifest names, each once, in manifest order. */
817
+ /** Every distinct object (digest and stored type) a manifest names, each once, in manifest order. */
818
818
  export declare function candidateManifestObjects(output: CandidateOutputManifest): readonly CandidateUpload[];
819
819
  /** Decode a stored backend descriptor; a manifest's backend must be one. */
820
820
  export declare function decodeCandidateBackend(bytes: Uint8Array): {
@@ -148,19 +148,19 @@ export const candidateObjectMediaTypes = [
148
148
  export function candidateObjectMediaType(value) {
149
149
  return candidateObjectMediaTypes.find((type) => type === value) ?? null;
150
150
  }
151
- /** Every distinct object a manifest names, each once, in manifest order. */
151
+ /** Every distinct object (digest and stored type) a manifest names, each once, in manifest order. */
152
152
  export function candidateManifestObjects(output) {
153
153
  const objects = [];
154
154
  const add = (object, mediaType) => {
155
- const seen = objects.find(({ digest }) => digest === object.digest);
156
- if (seen === undefined)
155
+ const named = objects.filter(({ digest }) => digest === object.digest);
156
+ if (named.some(({ byteLength }) => byteLength !== object.byteLength))
157
+ throw new Error("One object digest names two sizes");
158
+ if (!named.some((seen) => seen.mediaType === mediaType))
157
159
  objects.push({
158
160
  digest: object.digest,
159
161
  byteLength: object.byteLength,
160
162
  mediaType,
161
163
  });
162
- else if (seen.byteLength !== object.byteLength)
163
- throw new Error("One object digest names two sizes");
164
164
  };
165
165
  if (output.kind !== "backend") {
166
166
  const { content } = output.ui;
@@ -39,21 +39,22 @@ export declare function isBuildGitPrincipal<P extends Readonly<{
39
39
  * The build-report handler for `/jobs/:id/(candidate|artifact|status)` and
40
40
  * `PUT /jobs/:id/objects/sha256-<hex>`. `admitBuild` is the host's own
41
41
  * live-job lookup; `admitObject` admits one object upload for a live job's
42
- * grant and answers its size bound; `storeObject` streams an admitted object
43
- * into the host's content-addressed store, which verifies its digest;
42
+ * grant and answers its size bound (and whatever else the host's store needs,
43
+ * such as the owner namespace); `storeObject` streams an admitted object into
44
+ * the host's content-addressed store, which verifies its digest;
44
45
  * `submitCandidate` hands an admitted manifest to the host's Publisher
45
46
  * custody; `record` delivers a reported fact to the host's own projection.
46
47
  * `report` observes a body or JSON decode failure without changing its 400
47
48
  * outcome; a host may wire its own structured logger or omit it.
48
49
  */
49
- export declare function createBuildEgress(options: Readonly<{
50
+ export declare function createBuildEgress<Admission extends Readonly<{
51
+ maxObjectBytes: number;
52
+ }>>(options: Readonly<{
50
53
  admitBuild: (jobId: string) => Promise<Readonly<{
51
54
  credentialId: string;
52
55
  }> | null>;
53
- admitObject: (jobId: string, grant: string) => Promise<Readonly<{
54
- maxObjectBytes: number;
55
- }> | null>;
56
- storeObject: (object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType) => Promise<"stored" | "refused">;
56
+ admitObject: (jobId: string, grant: string) => Promise<Admission | null>;
57
+ storeObject: (object: CandidateObject, body: ReadableStream<Uint8Array> | null, mediaType: CandidateObjectMediaType, admitted: Admission) => Promise<"stored" | "refused">;
57
58
  submitCandidate: (jobId: string, manifest: TeamAppCandidateManifest, grant: string, credentialId: string) => Promise<Response>;
58
59
  record: (event: BuildGitEvent) => Promise<void>;
59
60
  report?: (operation: string, cause: unknown) => void;
@@ -34,8 +34,9 @@ export function isBuildGitPrincipal(principal) {
34
34
  * The build-report handler for `/jobs/:id/(candidate|artifact|status)` and
35
35
  * `PUT /jobs/:id/objects/sha256-<hex>`. `admitBuild` is the host's own
36
36
  * live-job lookup; `admitObject` admits one object upload for a live job's
37
- * grant and answers its size bound; `storeObject` streams an admitted object
38
- * into the host's content-addressed store, which verifies its digest;
37
+ * grant and answers its size bound (and whatever else the host's store needs,
38
+ * such as the owner namespace); `storeObject` streams an admitted object into
39
+ * the host's content-addressed store, which verifies its digest;
39
40
  * `submitCandidate` hands an admitted manifest to the host's Publisher
40
41
  * custody; `record` delivers a reported fact to the host's own projection.
41
42
  * `report` observes a body or JSON decode failure without changing its 400
@@ -67,7 +68,7 @@ export function createBuildEgress(options) {
67
68
  const stored = await options.storeObject(Schema.decodeUnknownSync(candidateObjectSchema)({
68
69
  digest: `sha256:${hex}`,
69
70
  byteLength,
70
- }), request.body, mediaType);
71
+ }), request.body, mediaType, admitted);
71
72
  return new Response(null, { status: stored === "stored" ? 204 : 400 });
72
73
  };
73
74
  return Object.freeze({
package/dist/build.d.ts CHANGED
@@ -9,4 +9,4 @@ export { frozenSnapshotInstallArguments } from "./build/snapshot-package-store.j
9
9
  export { repositoryEnvironment, artifactsGitEnvironment, hostedArtifactsGitRemote, } from "./build/git-environment.js";
10
10
  /** Captured-dependency build program with guarded filesystem access. */
11
11
  export declare const dependencyBuildProgram: string;
12
- export { stageBuildOutput, writeArtifactRoot, type ImmutableArtifactObjects, type StagedArtifactObject, type StagedBuildOutput, } from "./build/artifact-writer.js";
12
+ export { stageBuildOutput, writeArtifactRoot, type ImmutableArtifactObjects, type StagedArtifactObject, type StagedCandidateObject, type StagedBuildOutput, } from "./build/artifact-writer.js";
@@ -13,6 +13,8 @@ export type ConversationBinding = Readonly<{
13
13
  siteKey: string;
14
14
  origins: readonly string[];
15
15
  accent?: string | undefined;
16
+ /** Visitors must pass Turnstile before a mint. */
17
+ turnstile?: boolean | undefined;
16
18
  }> | Readonly<{
17
19
  provider: "discord" | "email" | "game";
18
20
  }>;
@@ -0,0 +1,33 @@
1
+ import type { ConversationBinding } from "./binding.js";
2
+ /**
3
+ * Whether one Session of an Agent may run, and under which channel binding.
4
+ * A channel never narrows or widens the Agent's own tools and permissions; it
5
+ * only admits or refuses the run. A missing, suspended or unreadable binding
6
+ * denies the run.
7
+ */
8
+ export type ChannelRunDecision<B extends ConversationBinding> = Readonly<{
9
+ kind: "private";
10
+ }> | Readonly<{
11
+ kind: "channel";
12
+ binding: B;
13
+ }> | Readonly<{
14
+ kind: "denied";
15
+ bindingId: string;
16
+ reason: ChannelDenial;
17
+ }>;
18
+ /** Why a channel Session may not run. */
19
+ export type ChannelDenial = "binding_missing" | "binding_suspended" | "lookup_failed";
20
+ /**
21
+ * Decide one Session. `conversationBindingId` is the binding the Session was
22
+ * opened under (null for an owner Session); `binding` is that binding as the
23
+ * Agent currently knows it, or null when it knows none.
24
+ */
25
+ export declare function decideChannelRun<B extends ConversationBinding>(input: Readonly<{
26
+ conversationBindingId: string | null;
27
+ binding: B | null;
28
+ }>): ChannelRunDecision<B>;
29
+ /** Run the lookup and decision together; a throwing lookup denies. */
30
+ export declare function decideChannelRunSafely<B extends ConversationBinding>(lookup: () => Readonly<{
31
+ conversationBindingId: string | null;
32
+ binding: B | null;
33
+ }>, sessionId: string, onFailure: (cause: unknown) => void): ChannelRunDecision<B>;
@@ -0,0 +1,25 @@
1
+ /**
2
+ * Decide one Session. `conversationBindingId` is the binding the Session was
3
+ * opened under (null for an owner Session); `binding` is that binding as the
4
+ * Agent currently knows it, or null when it knows none.
5
+ */
6
+ export function decideChannelRun(input) {
7
+ const { conversationBindingId: bindingId, binding } = input;
8
+ if (bindingId === null)
9
+ return { kind: "private" };
10
+ if (binding?.bindingId !== bindingId)
11
+ return { kind: "denied", bindingId, reason: "binding_missing" };
12
+ if (binding.lifecycle !== "active")
13
+ return { kind: "denied", bindingId, reason: "binding_suspended" };
14
+ return { kind: "channel", binding };
15
+ }
16
+ /** Run the lookup and decision together; a throwing lookup denies. */
17
+ export function decideChannelRunSafely(lookup, sessionId, onFailure) {
18
+ try {
19
+ return decideChannelRun(lookup());
20
+ }
21
+ catch (cause) {
22
+ onFailure(cause);
23
+ return { kind: "denied", bindingId: sessionId, reason: "lookup_failed" };
24
+ }
25
+ }