@sentropic/artifacts 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Fabien Antoine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @sentropic/artifacts — generic artifact contracts (L-5a)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Generic, host-independent artifact domain state for the Sentropic artifacts
+provider (`sentropic.artifacts`, spec-v8 §9), covering L-5a–5e. Version
+`0.1.1` fixes activation ticket release and channel binding (FL-ACT).
+
+## What's here (L-5a)
+
+- `src/contracts.ts` — schema versions, server-allocated UUID identities,
+  `CanonicalManifest`, JSON types. No server, driver or ORM imports.
+- `src/codecs.ts` — canonical manifest bytes (recursive key sort, arrays as
+  unordered sets, no `undefined`) + SHA-256 digest; `parseManifest`
+  fail-closed (sealed documents verify, working documents carry no digest).
+- `src/parameters.ts` — provider parameter schemas: defaults, unknown-key /
+  wrong-type / missing-required rejection, secret-looking key refusal.
+- `src/provider-definition.ts` — exact `publicName → (providerId, capability)`
+  map; duplicate and cross-provider collisions rejected, never sanitized.
+- `src/client.ts` — transport-free request builders / response parsers.
+- `src/server/ports.ts` — injected `KvPort` / `UuidPort` / per-key mutex.
+- `src/server/service.ts` — one service for HTTP and MCP: authorization
+  first, then idempotent binding ensure. Explicit ports, no defaults.
+- `src/server/authorization.ts` — owner-only, deny by default (no sharing
+  grants in this lot; sharing arrives in L-5c).
+- `src/server/bindings.ts` — owner-scoped stable bindings, scope fail-closed,
+  concurrent ensures converge.
+- `src/server/idempotency.ts` — one result per key, explicit conflicts.
+
+## Gates
+
+```sh
+make typecheck-artifacts API_PORT=9550 UI_PORT=5750 MAILDEV_UI_PORT=1650 ENV=test-immo-861-mcp-registry
+make test-artifacts API_PORT=9550 UI_PORT=5750 MAILDEV_UI_PORT=1650 ENV=test-immo-861-mcp-registry
+make test-artifacts-integration API_PORT=9550 UI_PORT=5750 MAILDEV_UI_PORT=1650 ENV=test-immo-861-mcp-registry
+```
+
+## What's here (L-5b–5c)
+
+- `src/server/access.ts` — owner/grants/approved-public evaluation + ACL store.
+- `src/server/sources.ts` — explicit source refs + source store.
+- `src/server/fork.ts` — private independent forks, no ACL copy, refcounted blobs.
+- `src/server/lifecycle.ts` — withdraw/restore/delete/purge, explicit
+  promote/rollback over the single publication current pointer, renew.
+- `src/server/gc.ts` — refcounts, pins, reported collection.
+- `src/http.ts` — transport-free HTTP app delegating to the same services
+  (401/403/404/409/410/422/400 mapping; reads never oracle existence).
+- `migrations/0001_artifacts.sql` — domain schema (manifest TEXT for
+  byte-identity). Sharing/lifecycle/GC tables arrive with the 0002 migration.
+
+No Immo defaults, URLs or bindings in generic source.
+
+## What's here (L-5d–5e)
+
+- `src/content/grants.ts` — 55s HMAC content grants (60s cutoff budget) and
+  single-use activation tickets bound to subject, artifact, exact release
+  and channel (`stable` or `pinned`); secrets and clocks are injected.
+- `src/content/routing.ts` — stable (`<artifactId>.<base>`) and pinned
+  (`<releaseId>.pinned.<base>`) single-UUID origins; safe path resolution.
+- `src/content/headers.ts` — no-store/nosniff/frame-denial/CSP headers and
+  the host-only `__Host-artifacts_grant` cookie.
+- `src/content/handler.ts` — transport-free content serving: per-version
+  activation, grant + live ACL recheck per request, raw bytes out.
+- `src/content/api-profile.ts` — reader-delegation profile: exact
+  method/route/binding checks plus Origin/CSRF evidence for writes.
+- `src/server/templates.ts` — generic template kit + versioned API guide
+  catalog port (hosts inject approved local assets).
+- `src/mcp.ts` — the `sentropic.artifacts` MCP provider: 15 exact
+  `artifacts_*` tools with closed schemas, a host-bindable invocation
+  scope, an executor over the same HTTP app, a platform adapter, and the
+  `@sentropic/mcp-platform` kernel registry definition (the platform is
+  an optional peer, required only by the `./mcp` subpath).
+
+Ticket issuance and redemption both require `subjectId`, `artifactId`,
+`releaseId` and `channel`. The handler checks the release resolved from the
+requested origin and its channel before minting a grant. A stable ticket
+issued for r1 cannot activate r2 after republish, and a stable ticket cannot
+activate a pinned origin (or vice versa). Mismatches return 401 without a
+grant cookie and preserve the ticket for a matching request. Tickets expire
+at `expiresAt` (120 seconds by default) and can be redeemed only once.
+
+## First publish (bootstrap)
+
+The steady-state OIDC job requires an npm trusted publisher. For the first
+publication, use the current package version and this bootstrap sequence
+(owner-run, never automated here):
+
+1. Trigger the `bootstrap-publish` workflow manually with
+   `bootstrap_publish_target=artifacts` (runs
+   `make publish-artifacts-token` with the `NPM_TOKEN` secret; no OIDC
+   provenance on the token publish). Locally equivalent:
+   `make publish-artifacts-token NPM_TOKEN_FILE=/path/to/token`.
+2. On npmjs.com, open `@sentropic/artifacts` → Settings → Trusted
+   Publishers and attach the GitHub Actions publisher for
+   `rhanka/sentropic` workflow `ci.yml`.
+3. After that, merges to `main` touching the artifacts package publish
+   through the `publish-artifacts` job (`make publish-artifacts`, OIDC +
+   provenance), gated by `validate-artifacts`.

package/dist/adapters/postgres.d.ts

@@ -0,0 +1,35 @@
+/**
+ * L-5b — Postgres adapter, part 1: stable bindings (spec-v8 §9).
+ *
+ * Over an injected pg Pool: no eager connections, no api/src imports, no DDL at
+ * runtime (the host applies `migrations/0001_artifacts.sql`). Concurrent ensures
+ * converge via INSERT ... ON CONFLICT DO NOTHING + reread. Parts 2-3 add
+ * intents, state promotion, idempotency and blob registration.
+ */
+import type { Pool } from 'pg';
+import type { JsonValue } from '../contracts.js';
+import type { AclStore } from '../server/access.js';
+import type { RefcountStore } from '../server/gc.js';
+import type { LifecycleStore } from '../server/lifecycle.js';
+import type { SourceStore } from '../server/sources.js';
+import type { IntentStore } from '../server/object-intents.js';
+import type { IdempotencyStore } from '../server/idempotency.js';
+import type { PublicationStateStore } from '../server/publication.js';
+export interface ArtifactBindingInput {
+    storageScopeId: string;
+    ownerId: string;
+    bindingName: string;
+    profile: Record<string, JsonValue | undefined>;
+}
+export interface ArtifactBinding {
+    artifactId: string;
+    created: boolean;
+}
+export interface PostgresArtifactBasics extends IntentStore {
+    ensureArtifact(input: ArtifactBindingInput): Promise<ArtifactBinding>;
+}
+export interface PostgresArtifactStore extends PostgresArtifactBasics, PublicationStateStore, IdempotencyStore, AclStore, SourceStore, LifecycleStore, RefcountStore {
+    listRegisteredBlobs(storageScopeId: string): Promise<string[]>;
+}
+/** Create the Postgres-backed store over an injected pool (no DDL). */
+export declare function createPostgresArtifactStore(pool: Pool): PostgresArtifactStore;

package/dist/adapters/postgres.js

@@ -0,0 +1,301 @@
+function toIntent(row) {
+    return {
+        intentId: row.id,
+        kind: row.kind,
+        state: row.state,
+        payload: row.payload,
+        error: row.error ?? undefined,
+        createdAt: row.created_at.toISOString(),
+        updatedAt: row.updated_at.toISOString(),
+    };
+}
+function toRelease(row) {
+    return {
+        releaseId: row.id,
+        artifactId: row.artifact_id,
+        manifestDigest: row.manifest_digest,
+        manifest: row.manifest,
+        state: row.state,
+        createdAt: row.created_at.toISOString(),
+    };
+}
+/** Create the Postgres-backed store over an injected pool (no DDL). */
+export function createPostgresArtifactStore(pool) {
+    return {
+        async ensureArtifact(input) {
+            const where = `WHERE storage_scope_id = $1 AND owner_id = $2 AND binding_name = $3`;
+            const args = [input.storageScopeId, input.ownerId, input.bindingName];
+            const found = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            if (found.rowCount !== 0 && found.rows[0] !== undefined) {
+                return { artifactId: found.rows[0].id, created: false };
+            }
+            const inserted = await pool.query(`INSERT INTO artifacts.artifacts (id, storage_scope_id, owner_id, binding_name, profile)
+         VALUES (gen_random_uuid(), $1, $2, $3, $4)
+         ON CONFLICT (storage_scope_id, owner_id, binding_name) DO NOTHING RETURNING id`, [...args, input.profile]);
+            if (inserted.rowCount !== 0 && inserted.rows[0] !== undefined) {
+                return { artifactId: inserted.rows[0].id, created: true };
+            }
+            const raced = await pool.query(`SELECT id FROM artifacts.artifacts ${where}`, args);
+            const row = raced.rows[0];
+            if (row === undefined)
+                throw new Error(`artifact binding lost for ${input.bindingName}`);
+            return { artifactId: row.id, created: false };
+        },
+        async record(kind, payload) {
+            const { rows } = await pool.query(`INSERT INTO artifacts.object_intents (id, kind, payload)
+         VALUES (gen_random_uuid(), $1, $2)
+         RETURNING id, kind, state, payload, error, created_at, updated_at`, [kind, payload]);
+            const row = rows[0];
+            if (row === undefined)
+                throw new Error('intent insert failed');
+            return toIntent(row);
+        },
+        async complete(intentId) {
+            const done = await pool.query(`UPDATE artifacts.object_intents SET state = 'done', updated_at = now() WHERE id = $1`, [intentId]);
+            if (done.rowCount === 0)
+                throw new Error(`unknown intent: ${intentId}`);
+        },
+        async markFailed(intentId, error) {
+            const failed = await pool.query(`UPDATE artifacts.object_intents SET state = 'failed', error = $2, updated_at = now() WHERE id = $1`, [intentId, error]);
+            if (failed.rowCount === 0)
+                throw new Error(`unknown intent: ${intentId}`);
+        },
+        async get(intentId) {
+            const { rows } = await pool.query(`SELECT id, kind, state, payload, error, created_at, updated_at
+         FROM artifacts.object_intents WHERE id = $1`, [intentId]);
+            const row = rows[0];
+            return row === undefined ? undefined : toIntent(row);
+        },
+        async listPending() {
+            const { rows } = await pool.query(`SELECT id, kind, state, payload, error, created_at, updated_at
+         FROM artifacts.object_intents WHERE state = 'pending' ORDER BY created_at`);
+            return rows.map(toIntent);
+        },
+        async putRelease(release) {
+            const parsed = JSON.parse(release.manifest);
+            const client = await pool.connect();
+            try {
+                await client.query('BEGIN');
+                await client.query(`INSERT INTO artifacts.releases (id, artifact_id, manifest_digest, manifest, state, created_at)
+           VALUES ($1, $2, $3, $4, 'ready', $5)`, [release.releaseId, release.artifactId, release.manifestDigest, release.manifest, release.createdAt]);
+                const scope = await client.query(`SELECT storage_scope_id FROM artifacts.artifacts WHERE id = $1`, [release.artifactId]);
+                const scopeId = scope.rows[0]?.storage_scope_id;
+                if (scopeId === undefined)
+                    throw new Error(`unknown artifact: ${release.artifactId}`);
+                for (const file of parsed.files ?? []) {
+                    if (typeof file.digest !== 'string' || typeof file.size !== 'number')
+                        continue;
+                    await client.query(`INSERT INTO artifacts.blobs (storage_scope_id, digest, size)
+             VALUES ($1, $2, $3) ON CONFLICT DO NOTHING`, [scopeId, file.digest, file.size]);
+                }
+                await client.query('COMMIT');
+            }
+            catch (error) {
+                await client.query('ROLLBACK');
+                throw error;
+            }
+            finally {
+                client.release();
+            }
+        },
+        async getRelease(releaseId) {
+            const { rows } = await pool.query(`SELECT id, artifact_id, manifest_digest, manifest, state, created_at
+         FROM artifacts.releases WHERE id = $1`, [releaseId]);
+            const row = rows[0];
+            return row === undefined ? undefined : toRelease(row);
+        },
+        async getCurrentReleaseId(artifactId) {
+            const { rows } = await pool.query(`SELECT release_id FROM artifacts.artifact_current WHERE artifact_id = $1`, [artifactId]);
+            return rows[0]?.release_id;
+        },
+        async compareAndSwapCurrent(artifactId, expected, next) {
+            if (expected === null) {
+                const inserted = await pool.query(`INSERT INTO artifacts.artifact_current (artifact_id, release_id)
+           VALUES ($1, $2) ON CONFLICT (artifact_id) DO NOTHING`, [artifactId, next]);
+                return (inserted.rowCount ?? 0) !== 0;
+            }
+            const updated = await pool.query(`UPDATE artifacts.artifact_current SET release_id = $3
+         WHERE artifact_id = $1 AND release_id = $2`, [artifactId, expected, next]);
+            return (updated.rowCount ?? 0) !== 0;
+        },
+        async execute(key, paramsHash, work) {
+            const found = await pool.query(`SELECT params_hash, result FROM artifacts.idempotency_keys WHERE key = $1`, [`idempotency:${key}`]);
+            const stored = found.rows[0];
+            if (stored !== undefined) {
+                if (stored.params_hash !== paramsHash) {
+                    throw new Error(`idempotency conflict: key ${key} already used with different parameters`);
+                }
+                return { result: stored.result, replayed: true };
+            }
+            const result = await work();
+            const inserted = await pool.query(`INSERT INTO artifacts.idempotency_keys (key, params_hash, result)
+         VALUES ($1, $2, $3) ON CONFLICT (key) DO NOTHING RETURNING key`, [`idempotency:${key}`, paramsHash, JSON.stringify(result)]);
+            if ((inserted.rowCount ?? 0) !== 0)
+                return { result, replayed: false };
+            const raced = await pool.query(`SELECT params_hash, result FROM artifacts.idempotency_keys WHERE key = $1`, [`idempotency:${key}`]);
+            const winner = raced.rows[0];
+            if (winner === undefined)
+                throw new Error(`idempotency record lost for ${key}`);
+            if (winner.params_hash !== paramsHash) {
+                throw new Error(`idempotency conflict: key ${key} already used with different parameters`);
+            }
+            return { result: winner.result, replayed: true };
+        },
+        async listRegisteredBlobs(storageScopeId) {
+            const { rows } = await pool.query(`SELECT digest FROM artifacts.blobs WHERE storage_scope_id = $1 ORDER BY digest`, [storageScopeId]);
+            return rows.map((row) => row.digest);
+        },
+        async getArtifactAcl(artifactId) {
+            const { rows } = await pool.query(`SELECT owner_id, storage_scope_id, is_public, lifecycle_state
+         FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            const row = rows[0];
+            if (row === undefined)
+                return undefined;
+            const grants = await pool.query(`SELECT principal_id, permission FROM artifacts.artifact_access
+         WHERE artifact_id = $1 ORDER BY principal_id`, [artifactId]);
+            return {
+                ownerId: row.owner_id,
+                storageScopeId: row.storage_scope_id,
+                isPublic: row.is_public,
+                withdrawn: row.lifecycle_state === 'withdrawn',
+                grants: grants.rows.map((grant) => ({
+                    principalId: grant.principal_id,
+                    grant: grant.permission,
+                })),
+            };
+        },
+        async putArtifactAcl(artifactId, acl) {
+            await pool.query(`UPDATE artifacts.artifacts SET is_public = $2,
+         lifecycle_state = CASE WHEN $3 THEN 'withdrawn'
+           WHEN lifecycle_state = 'withdrawn' THEN 'active'
+           ELSE lifecycle_state END
+         WHERE id = $1`, [artifactId, acl.isPublic, acl.withdrawn]);
+            await pool.query(`DELETE FROM artifacts.artifact_access WHERE artifact_id = $1`, [
+                artifactId,
+            ]);
+            for (const grant of acl.grants) {
+                await pool.query(`INSERT INTO artifacts.artifact_access (artifact_id, principal_id, permission)
+           VALUES ($1, $2, $3)`, [artifactId, grant.principalId, grant.grant]);
+            }
+        },
+        async listArtifactIds() {
+            const { rows } = await pool.query(`SELECT id FROM artifacts.artifacts ORDER BY created_at ASC, id ASC`);
+            return rows.map((row) => row.id);
+        },
+        async getSource(artifactId) {
+            const { rows } = await pool.query(`SELECT kind, commit_tx, steps FROM artifacts.artifact_sources WHERE artifact_id = $1`, [artifactId]);
+            const row = rows[0];
+            if (row === undefined)
+                return undefined;
+            if (row.kind === 'inline-original')
+                return { kind: 'inline-original' };
+            if (row.kind === 'base-commit') {
+                return { kind: 'base-commit', commit: row.commit_tx ?? '' };
+            }
+            if (row.kind === 'recipe') {
+                return {
+                    kind: 'recipe',
+                    steps: Array.isArray(row.steps) ? row.steps.map((step) => String(step)) : [],
+                };
+            }
+            throw new Error(`unknown source kind: ${row.kind}`);
+        },
+        async putSource(artifactId, source) {
+            const commit = source.kind === 'base-commit' ? source.commit : null;
+            const steps = source.kind === 'recipe' ? JSON.stringify(source.steps) : null;
+            await pool.query(`INSERT INTO artifacts.artifact_sources (artifact_id, kind, commit_tx, steps)
+         VALUES ($1, $2, $3, $4::jsonb)
+         ON CONFLICT (artifact_id) DO UPDATE
+         SET kind = EXCLUDED.kind, commit_tx = EXCLUDED.commit_tx, steps = EXCLUDED.steps`, [artifactId, source.kind, commit, steps]);
+        },
+        async register(artifactId, ownerId) {
+            const { rows } = await pool.query(`SELECT owner_id FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            const row = rows[0];
+            if (row === undefined)
+                throw new Error(`unknown artifact: ${artifactId}`);
+            if (row.owner_id !== ownerId)
+                throw new Error(`owner mismatch for ${artifactId}`);
+        },
+        async getOwner(artifactId) {
+            const { rows } = await pool.query(`SELECT owner_id FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            return rows[0]?.owner_id;
+        },
+        async getArtifactState(artifactId) {
+            const { rows } = await pool.query(`SELECT lifecycle_state FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            return rows[0]?.lifecycle_state ?? 'active';
+        },
+        async setArtifactState(artifactId, state) {
+            const updated = await pool.query(`UPDATE artifacts.artifacts SET lifecycle_state = $2 WHERE id = $1`, [artifactId, state]);
+            if ((updated.rowCount ?? 0) === 0)
+                throw new Error(`unknown artifact: ${artifactId}`);
+        },
+        async getRenewedAt(artifactId) {
+            const { rows } = await pool.query(`SELECT renewed_at FROM artifacts.artifacts WHERE id = $1`, [artifactId]);
+            return rows[0]?.renewed_at?.toISOString();
+        },
+        async setRenewedAt(artifactId, renewedAt) {
+            const updated = await pool.query(`UPDATE artifacts.artifacts SET renewed_at = $2 WHERE id = $1`, [artifactId, renewedAt]);
+            if ((updated.rowCount ?? 0) === 0)
+                throw new Error(`unknown artifact: ${artifactId}`);
+        },
+        async addRelease(artifactId, releaseId) {
+            const artifact = await pool.query(`SELECT id FROM artifacts.artifacts WHERE id = $1`, [
+                artifactId,
+            ]);
+            if ((artifact.rowCount ?? 0) === 0)
+                throw new Error(`unknown artifact: ${artifactId}`);
+            const release = await pool.query(`SELECT id FROM artifacts.releases WHERE id = $1`, [
+                releaseId,
+            ]);
+            if ((release.rowCount ?? 0) === 0)
+                throw new Error(`unknown release: ${releaseId}`);
+        },
+        async listArtifactReleases(artifactId) {
+            const { rows } = await pool.query(`SELECT id FROM artifacts.releases WHERE artifact_id = $1 ORDER BY created_at, id`, [artifactId]);
+            return rows.map((row) => row.id);
+        },
+        async getReleaseState(releaseId) {
+            const { rows } = await pool.query(`SELECT state FROM artifacts.releases WHERE id = $1`, [releaseId]);
+            return rows[0]?.state ?? 'ready';
+        },
+        async setReleaseState(releaseId, state) {
+            const updated = await pool.query(`UPDATE artifacts.releases SET state = $2 WHERE id = $1`, [
+                releaseId,
+                state,
+            ]);
+            if ((updated.rowCount ?? 0) === 0)
+                throw new Error(`unknown release: ${releaseId}`);
+        },
+        async addRef(digest, holder) {
+            await pool.query(`INSERT INTO artifacts.blob_ref_holders (digest, holder) VALUES ($1, $2)
+         ON CONFLICT (digest, holder) DO NOTHING`, [digest, holder]);
+        },
+        async releaseRef(digest, holder) {
+            const deleted = await pool.query(`DELETE FROM artifacts.blob_ref_holders WHERE digest = $1 AND holder = $2`, [digest, holder]);
+            if ((deleted.rowCount ?? 0) === 0) {
+                throw new Error(`refcount not held: ${digest} by ${holder}`);
+            }
+        },
+        async pin(digest, reason) {
+            const inserted = await pool.query(`INSERT INTO artifacts.blob_pins (digest, reason) VALUES ($1, $2)
+         ON CONFLICT (digest, reason) DO NOTHING RETURNING digest`, [digest, reason]);
+            if ((inserted.rowCount ?? 0) === 0) {
+                throw new Error(`duplicate pin: ${digest} (${reason})`);
+            }
+        },
+        async unpin(digest, reason) {
+            const deleted = await pool.query(`DELETE FROM artifacts.blob_pins WHERE digest = $1 AND reason = $2`, [digest, reason]);
+            if ((deleted.rowCount ?? 0) === 0) {
+                throw new Error(`not pinned: ${digest} (${reason})`);
+            }
+        },
+        async count(digest) {
+            const { rows } = await pool.query(`SELECT COUNT(*) AS total FROM artifacts.blob_ref_holders WHERE digest = $1`, [digest]);
+            return Number(rows[0]?.total ?? 0);
+        },
+        async isPinned(digest) {
+            const { rows } = await pool.query(`SELECT EXISTS (SELECT 1 FROM artifacts.blob_pins WHERE digest = $1) AS found`, [digest]);
+            return rows[0]?.found ?? false;
+        },
+    };
+}

package/dist/adapters/s3.d.ts

@@ -0,0 +1,19 @@
+/**
+ * L-5b — S3 adapter: digest-addressed blob store (spec-v8 §9).
+ *
+ * Implements PublicationBlobStore over an injected S3 client and bucket.
+ * Only keys under `artifacts/<scope>/blobs/sha256/<64 hex>` are accepted;
+ * anything else (traversal, absolute paths, foreign prefixes, non-hex
+ * digests) is refused before any network call. Absent objects read as
+ * undefined; listing is prefix-scoped and sorted (orphan enumeration).
+ * The client (endpoint, region, credentials, path style) is built by the
+ * host and injected — this module never reads env or creates connections.
+ */
+import { type S3Client } from '@aws-sdk/client-s3';
+import type { PublicationBlobStore } from '../server/publication.js';
+export interface S3BlobStoreOptions {
+    client: S3Client;
+    bucket: string;
+}
+/** Create an S3-backed blob store over an injected client (no env reads). */
+export declare function createS3BlobStore(options: S3BlobStoreOptions): PublicationBlobStore;

package/dist/adapters/s3.js

@@ -0,0 +1,70 @@
+/**
+ * L-5b — S3 adapter: digest-addressed blob store (spec-v8 §9).
+ *
+ * Implements PublicationBlobStore over an injected S3 client and bucket.
+ * Only keys under `artifacts/<scope>/blobs/sha256/<64 hex>` are accepted;
+ * anything else (traversal, absolute paths, foreign prefixes, non-hex
+ * digests) is refused before any network call. Absent objects read as
+ * undefined; listing is prefix-scoped and sorted (orphan enumeration).
+ * The client (endpoint, region, credentials, path style) is built by the
+ * host and injected — this module never reads env or creates connections.
+ */
+import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, } from '@aws-sdk/client-s3';
+const BLOB_KEY_PATTERN = /^artifacts\/[A-Za-z0-9_-]+\/blobs\/sha256\/[0-9a-f]{64}$/;
+/** Reject anything but digest-addressed blob keys, before any I/O. */
+function assertBlobKey(key) {
+    if (!BLOB_KEY_PATTERN.test(key)) {
+        throw new Error(`invalid blob key (must be artifacts/<scope>/blobs/sha256/<hex>): ${key}`);
+    }
+}
+/** Reject empty or escaping prefixes before any I/O. */
+function assertPrefix(prefix) {
+    if (prefix.length === 0 || prefix.includes('..')) {
+        throw new Error(`invalid blob prefix: ${prefix}`);
+    }
+}
+/** Create an S3-backed blob store over an injected client (no env reads). */
+export function createS3BlobStore(options) {
+    return {
+        async putBlob(key, bytes) {
+            assertBlobKey(key);
+            await options.client.send(new PutObjectCommand({ Bucket: options.bucket, Key: key, Body: bytes }));
+        },
+        async getBlob(key) {
+            assertBlobKey(key);
+            try {
+                const out = await options.client.send(new GetObjectCommand({ Bucket: options.bucket, Key: key }));
+                if (out.Body === undefined)
+                    return undefined;
+                const collected = await out.Body.transformToByteArray();
+                return new Uint8Array(collected);
+            }
+            catch (error) {
+                if (typeof error === 'object' && error !== null && 'name' in error) {
+                    const name = error.name;
+                    if (name === 'NoSuchKey' || name === 'NotFound')
+                        return undefined;
+                }
+                throw error;
+            }
+        },
+        async listKeys(prefix) {
+            assertPrefix(prefix);
+            const keys = [];
+            let token;
+            do {
+                const out = await options.client.send(new ListObjectsV2Command({ Bucket: options.bucket, Prefix: prefix, ContinuationToken: token }));
+                for (const entry of out.Contents ?? []) {
+                    if (entry.Key !== undefined)
+                        keys.push(entry.Key);
+                }
+                token = out.IsTruncated === true ? out.NextContinuationToken : undefined;
+            } while (token !== undefined);
+            return keys.sort();
+        },
+        async deleteBlob(key) {
+            assertBlobKey(key);
+            await options.client.send(new DeleteObjectCommand({ Bucket: options.bucket, Key: key }));
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,23 @@
+import { type ParameterSchema } from './parameters.js';
+export interface EnsureRequest {
+    bindingName: string;
+    storageScopeId: string;
+    idempotencyKey: string;
+    paramsHash: string;
+    parameters: Record<string, string | number | boolean | null>;
+}
+export interface EnsureResponse {
+    artifactId: string;
+    created: boolean;
+    replayed: boolean;
+}
+/** Build a validated ensure request for a provider's parameter schema. */
+export declare function buildEnsureRequest(schema: ParameterSchema, input: {
+    bindingName: string;
+    storageScopeId: string;
+    idempotencyKey: string;
+    paramsHash: string;
+    parameters: Record<string, string | number | boolean | null | undefined>;
+}): EnsureRequest;
+/** Parse and validate an ensure response (server-allocated identity). */
+export declare function parseEnsureResponse(raw: unknown): EnsureResponse;

package/dist/client.js

@@ -0,0 +1,44 @@
+/**
+ * L-5a — public artifact client builders (spec-v8 §9).
+ *
+ * No I/O, no server, driver or cluster-mesh imports: this module builds
+ * validated ensure requests and parses ensure responses for any transport
+ * (HTTP in L-5c, MCP in L-5e). Parameter values are validated against the
+ * provider's schema up front; response identities are checked to be
+ * server-allocated UUIDs clients cannot forge.
+ */
+import { isArtifactId } from './contracts.js';
+import { validateParameters } from './parameters.js';
+/** Build a validated ensure request for a provider's parameter schema. */
+export function buildEnsureRequest(schema, input) {
+    if (input.bindingName.length === 0)
+        throw new Error('invalid ensure request: empty bindingName');
+    if (input.storageScopeId.length === 0)
+        throw new Error('invalid ensure request: empty storageScopeId');
+    if (input.idempotencyKey.length === 0)
+        throw new Error('invalid ensure request: empty idempotencyKey');
+    const parameters = validateParameters(schema, input.parameters);
+    return {
+        bindingName: input.bindingName,
+        storageScopeId: input.storageScopeId,
+        idempotencyKey: input.idempotencyKey,
+        paramsHash: input.paramsHash,
+        parameters,
+    };
+}
+/** Parse and validate an ensure response (server-allocated identity). */
+export function parseEnsureResponse(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        throw new Error('invalid ensure response: not an object');
+    const response = raw;
+    if (!isArtifactId(response['artifactId']))
+        throw new Error('invalid ensure response: forged artifactId');
+    if (typeof response['created'] !== 'boolean' || typeof response['replayed'] !== 'boolean') {
+        throw new Error('invalid ensure response: bad flags');
+    }
+    return {
+        artifactId: response['artifactId'],
+        created: response['created'],
+        replayed: response['replayed'],
+    };
+}

package/dist/codecs.d.ts

@@ -0,0 +1,12 @@
+import { type CanonicalManifest } from './contracts.js';
+/** Deterministic serialization of a manifest (recursive key sort, no `undefined`). */
+export declare function canonicalManifest(manifest: CanonicalManifest): string;
+/** SHA-256 hex digest of the canonical manifest bytes. */
+export declare function manifestDigest(manifest: CanonicalManifest): string;
+/**
+ * Parse and validate a manifest, fail-closed: JSON object, known schema
+ * version, required `artifactId`. A present `digest` must match the body
+ * recomputed without it; an absent digest means unsealed working document
+ * (construction precedes sealing) and is accepted as-is.
+ */
+export declare function parseManifest(raw: string): CanonicalManifest;