@sentropic/artifacts 0.1.3 → 0.2.0

package/README.md

@@ -4,6 +4,76 @@ Generic, host-independent artifact domain state for the Sentropic artifacts
 provider (`sentropic.artifacts`, spec-v8 §9), covering L-5a–5e. Version
 `0.1.2` adds UTF-8 text publication, exposes storage adapters and ships SQL migrations.
 Version `0.1.1` fixed activation ticket release and channel binding (FL-ACT).
+Version `0.1.4` hardens host authority, replay isolation, publication and content
+responses, and adds the platform-free `@sentropic/artifacts/mcp-core` entry.
+
+## 0.2.0 contract line (L0 frozen)
+
+The `0.2.0` line freezes the immo #861 declaration shapes only:
+explicit capability selection and the effective publication profile
+(`l0-freeze/profile-contract.ts`), the effective command identity
+(`l0-freeze/command-identity-contract.ts`), the commit finalization unit
+(`l0-freeze/commit-contract.ts`) and the typed failure outcome
+(`l0-freeze/failure-contract.ts`). The section 3.2 host API names are frozen
+against spec r2. Trusted scope/subject domain qualification and
+actor-mapping acceptance remain gated on i-cond Q0; the structural freeze
+is not a completed Q0-dependent qualification. L1+ promotes the shapes
+into `src/`; version reservations are pack-only dev versions owned by the
+integration owner, never registry candidates. The common-contract reuse map lives in
+`docs/common-contract-map.md`; the migration inventory lives in
+`docs/migration-inventory-l0.md`. L0 changes no behavior, no `src/` file
+and no package version.
+
+## Migrating to 0.1.4
+
+HTTP hosts must supply a trusted `HttpRequest.storageScopeId` for `/ensure`.
+MCP hosts configure `defaultStorageScopeId` or supply the trusted invocation's
+`ArtifactsInvokeInput.storageScopeId`; tool arguments cannot choose storage.
+Legacy body/tool `storageScopeId` and client `paramsHash` fields remain accepted
+but are ignored. Missing host scope now returns 400. Ensure hashes cover the
+validated parameters, binding, owner and scope; publication hashes cover release
+metadata, server-derived file digests and validated source provenance (including
+its absence and recipe step order). Source writes occur within the idempotent
+publication operation, so unchanged replays do not write provenance again.
+Direct service callers publishing a `source` pass their host `SourceStore` as
+the second argument to `publish`; the HTTP/MCP app supplies its configured store.
+Keys are isolated by operation and
+principal. A changed payload under the same key returns an explicit conflict.
+Persisted unscoped replay keys are no longer consulted after upgrading.
+
+Publication defaults to 128 files, 16 MiB per file and 64 MiB total. Hosts can
+override these positive integer limits through `createPublicationService({
+limits: { maxFiles, maxFileBytes, maxTotalBytes } })`; the HTTP decoder uses the
+same byte budgets before allocating bytes. Paths must be unique canonical
+relative paths, at most 1024 UTF-8 bytes: empty/dot segments, backslashes,
+percent escapes, URL delimiters, colons and control characters are rejected.
+Existing integrations using larger bundles or noncanonical paths must adjust
+their limits or filenames. Invalid publications fail before object-store effects.
+Upload sessions cap client `maxSize` by the host `maxUploadBytes` and publication
+file/total limits. Every append checks remaining cumulative capacity before
+decoding bytes or writing staging. Upload publication metadata is validated
+before the session is consumed; a rejected path or MIME type can be corrected
+and committed using the same staged bytes. Finalization validates, hashes and
+publishes one copied snapshot. Overlapping append/commit operations return 409;
+failed verification or metadata validation leaves the session retryable.
+
+Content `HEAD` responses have the corresponding GET headers and no body,
+including errors and activation. Errors and activation responses include the
+same security and no-store headers as content responses, with a restrictive CSP.
+
+Import `createArtifactsManifest`, `createArtifactsToolExecutor` or
+`createArtifactsAdapter` from `@sentropic/artifacts/mcp-core` when the platform
+is absent. This entry has no runtime platform import. Existing `/mcp` exports,
+including `createArtifactsRegistryDefinition`, retain their platform integration.
+The existing root barrel re-exports `/mcp` and also requires the platform.
+Platform types remain referenced in TypeScript declarations for adapter typing.
+`make probe-artifacts-packed-consumer ENV=test-artifacts-hardening` installs the
+tarball alone in a separate consumer, proves the platform is absent and runs the
+15-tool manifest and ensure/publish/get/list flow before the platform proof.
+
+Release coordination: #707 reserves 0.1.3 for optional platform peer widening;
+0.1.4 retains `>=0.3.0 <0.5.0` and fits cluster-mesh's current
+`>=0.1.0 <0.2.0` and #707's `>=0.1.3 <0.2.0` artifacts ranges.
 
 ## What's here (L-5a)
 
@@ -137,11 +207,11 @@ a registrable domain. Assets within the same artifact origin remain loadable.
   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
+- `src/mcp-core.ts` — the platform-free `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).
+  scope, an executor over the same HTTP app and a platform adapter.
+- `src/mcp.ts` — the compatible `@sentropic/mcp-platform` kernel registry
+  definition wrapper (the optional peer is required here and by the root barrel).
 
 Ticket issuance and redemption both require `subjectId`, `artifactId`,
 `releaseId` and `channel`. The handler checks the release resolved from the

package/dist/adapters/postgres-commit.d.ts

@@ -0,0 +1,15 @@
+/**
+ * L3 (immo #861) — PostgreSQL finalization executor (spec r2 §3.1 A4).
+ *
+ * Owns every coordinator SQL statement against coordinator tables only
+ * (`artifacts.operation_keys`, `artifacts.operation_receipts`). No domain
+ * table, no policy table and no caller SQL here: host domain reads and
+ * writes arrive through the participant and the provider-internal
+ * transaction handle. Connections are raw pooled clients; the coordinator
+ * owns BEGIN/COMMIT/rollback/release. No nested pool lease spans S3 I/O:
+ * preparation happens before the coordinator acquires its client.
+ */
+import type { Pool } from 'pg';
+import type { CommitExecutor } from '../server/commit/types.js';
+/** Create the PostgreSQL finalization executor over an injected pool (no DDL). */
+export declare function createPostgresCommitExecutor(pool: Pool): CommitExecutor;

package/dist/adapters/postgres-commit.js

@@ -0,0 +1,80 @@
+function toReceipt(row) {
+    return {
+        scopeId: row.storage_scope_id,
+        internalKey: row.internal_key,
+        commandHash: row.command_hash,
+        codecVersion: row.command_codec,
+        receipt: row.receipt,
+        createdAt: row.created_at.toISOString(),
+    };
+}
+class PgFinalizeConnection {
+    client;
+    released = false;
+    constructor(client) {
+        this.client = client;
+    }
+    async query(text, params) {
+        const result = await this.client.query(text, [...params]);
+        return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+    }
+    async beginReadCommitted() {
+        await this.client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+    }
+    async lockOperationKey(scopeId, internalKey) {
+        await this.client.query(`SELECT 1 FROM artifacts.operation_keys
+       WHERE storage_scope_id = $1 AND internal_key = $2 FOR UPDATE`, [scopeId, internalKey]);
+    }
+    async readReceipt(scopeId, internalKey) {
+        const result = await this.client.query(`SELECT storage_scope_id, internal_key, command_codec, command_hash, receipt, created_at
+       FROM artifacts.operation_receipts
+       WHERE storage_scope_id = $1 AND internal_key = $2`, [scopeId, internalKey]);
+        const row = result.rows[0];
+        return row === undefined ? undefined : toReceipt(row);
+    }
+    async insertReceipt(receipt) {
+        await this.client.query(`INSERT INTO artifacts.operation_receipts
+         (storage_scope_id, internal_key, command_codec, command_hash, receipt)
+       VALUES ($1, $2, $3, $4, $5)`, [
+            receipt.scopeId,
+            receipt.internalKey,
+            receipt.codecVersion,
+            receipt.commandHash,
+            JSON.stringify(receipt.receipt),
+        ]);
+    }
+    async commit() {
+        await this.client.query('COMMIT');
+    }
+    async rollback() {
+        await this.client.query('ROLLBACK');
+    }
+    release(error) {
+        if (this.released)
+            throw new Error('finalization client already released');
+        this.released = true;
+        this.client.release(error === undefined ? undefined : error);
+    }
+}
+/** Create the PostgreSQL finalization executor over an injected pool (no DDL). */
+export function createPostgresCommitExecutor(pool) {
+    return {
+        async ensureCoordinationRow(scopeId, internalKey) {
+            await pool.query(`INSERT INTO artifacts.operation_keys (storage_scope_id, internal_key)
+         VALUES ($1, $2) ON CONFLICT DO NOTHING`, [scopeId, internalKey]);
+        },
+        async beginFinalization() {
+            const client = await pool.connect();
+            try {
+                await client.query('BEGIN ISOLATION LEVEL READ COMMITTED');
+            }
+            catch (error) {
+                // Never hand out a client whose transaction failed to open: destroy
+                // it instead of leaking a leased connection the coordinator cannot see.
+                client.release(error);
+                throw error;
+            }
+            return new PgFinalizeConnection(client);
+        },
+    };
+}

package/dist/adapters/postgres.d.ts

@@ -12,9 +12,12 @@ 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 { PreparationIntentStore } from '../server/object-intents.js';
 import type { IdempotencyStore } from '../server/idempotency.js';
 import type { PublicationStateStore } from '../server/publication.js';
+import type { KvPort } from '../server/ports.js';
+/** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
+export declare function createPostgresLegacyArtifactRecords(pool: Pool): Pick<KvPort, 'get'>;
 export interface ArtifactBindingInput {
     storageScopeId: string;
     ownerId: string;
@@ -25,7 +28,7 @@ export interface ArtifactBinding {
     artifactId: string;
     created: boolean;
 }
-export interface PostgresArtifactBasics extends IntentStore {
+export interface PostgresArtifactBasics extends PreparationIntentStore {
     ensureArtifact(input: ArtifactBindingInput): Promise<ArtifactBinding>;
 }
 export interface PostgresArtifactStore extends PostgresArtifactBasics, PublicationStateStore, IdempotencyStore, AclStore, SourceStore, LifecycleStore, RefcountStore {

package/dist/adapters/postgres.js

@@ -1,3 +1,12 @@
+/** Read-only migration inventory. Never promotes a legacy success into an authorized receipt. */
+export function createPostgresLegacyArtifactRecords(pool) {
+    return {
+        async get(key) {
+            const { rows } = await pool.query('SELECT params_hash, result FROM artifacts.idempotency_keys WHERE key = $1', [key]);
+            return rows[0] === undefined ? undefined : JSON.stringify(rows[0]);
+        },
+    };
+}
 function toIntent(row) {
     return {
         intentId: row.id,
@@ -71,6 +80,36 @@ export function createPostgresArtifactStore(pool) {
          FROM artifacts.object_intents WHERE state = 'pending' ORDER BY created_at`);
             return rows.map(toIntent);
         },
+        async listPreparationIntents(query = {}) {
+            const { rows } = await pool.query(`SELECT * FROM artifacts.object_intents WHERE kind = 'commit-release' AND state <> 'done'
+         AND payload ? 'cleanupDeadlineMs'
+         AND ($1::text IS NULL OR payload->>'artifactId' = $1)
+         AND ($2::numeric IS NULL OR (COALESCE(error, '') NOT LIKE 'invalid preparation metadata%'
+           AND
+           CASE WHEN jsonb_typeof(payload->'cleanupDeadlineMs') = 'number'
+             THEN (payload->>'cleanupDeadlineMs')::numeric ELSE 0 END <= $2
+           AND (payload->>'cleanupState' IS DISTINCT FROM 'failed-cleaned'
+             OR (payload->>'cleanupDeadlineMs')::numeric >= $2 - 60000)))
+         ORDER BY COALESCE(payload->>'cleanupState' = 'failed-cleaned', false),
+           CASE WHEN jsonb_typeof(payload->'cleanupDeadlineMs') = 'number'
+             THEN (payload->>'cleanupDeadlineMs')::numeric ELSE 0 END, id
+         LIMIT $3`, [query.artifactId ?? null, query.throughMs ?? null, query.limit ?? null]);
+            return rows.map(toIntent);
+        },
+        async claimPreparationCleanup(intentId, throughMs) {
+            // This UPDATE serializes with finalization's intent completion on the same row.
+            const { rows } = await pool.query(`UPDATE artifacts.object_intents SET state = 'failed',
+           error = COALESCE(error, 'preparation expired; explicit retry required'), updated_at = now()
+         WHERE id = $1 AND kind = 'commit-release' AND state <> 'done'
+           AND (payload->>'cleanupDeadlineMs')::numeric <= $2 RETURNING *`, [intentId, throughMs]);
+            return rows[0] === undefined ? undefined : toIntent(rows[0]);
+        },
+        async settlePreparationCleanup(intentId) {
+            const { rowCount } = await pool.query(`UPDATE artifacts.object_intents SET payload = payload || '{"cleanupState":"failed-cleaned"}'::jsonb,
+           updated_at = now() WHERE id = $1 AND state = 'failed'`, [intentId]);
+            if (rowCount === 0)
+                throw new Error('cleanup needs a failed preparation');
+        },
         async putRelease(release) {
             const parsed = JSON.parse(release.manifest);
             const client = await pool.connect();

package/dist/content/handler.js

@@ -13,8 +13,15 @@ import { errorBody } from '../http.js';
 import { CONTENT_GRANT_TTL_SECONDS } from './grants.js';
 import { contentHeaders, grantCookie, parseGrantCookie } from './headers.js';
 import { isServiceWorkerPath, parseContentHost, resolveContentPath } from './routing.js';
+function jsonResponse(status, body, extra = {}) {
+    return { status, body, headers: {
+            ...contentHeaders({ mimeType: 'application/json', size: Buffer.byteLength(JSON.stringify(body)) }),
+            'content-security-policy': "default-src 'none'; frame-ancestors 'none'; base-uri 'none'",
+            ...extra,
+        } };
+}
 function fail(status) {
-    return { status, headers: { 'content-type': 'application/json' }, body: errorBody(status) };
+    return jsonResponse(status, errorBody(status));
 }
 /** Create the content handler over injected host ports (no server). */
 export function createContentHandler(deps) {
@@ -52,78 +59,87 @@ export function createContentHandler(deps) {
             bytes,
         };
     }
-    return {
-        async handle(request) {
-            if (request.method !== 'GET' && request.method !== 'HEAD')
-                return fail(404);
-            const origin = parseContentHost(request.host, deps.baseDomain);
-            if (origin === undefined)
-                return fail(404);
-            let artifactId;
-            let release;
-            if (origin.kind === 'stable') {
-                artifactId = origin.artifactId;
-                release = await deps.publication.getCurrent(artifactId);
-            }
-            else {
-                release = await deps.publication.getRelease(origin.releaseId);
-                if (release === undefined)
-                    return fail(404);
-                const owner = JSON.parse(release.manifest).artifactId;
-                if (typeof owner !== 'string')
-                    return fail(404);
-                artifactId = owner;
-            }
+    async function handle(request) {
+        if (request.method !== 'GET' && request.method !== 'HEAD')
+            return fail(404);
+        const origin = parseContentHost(request.host, deps.baseDomain);
+        if (origin === undefined)
+            return fail(404);
+        let artifactId;
+        let release;
+        if (origin.kind === 'stable') {
+            artifactId = origin.artifactId;
+            release = await deps.publication.getCurrent(artifactId);
+        }
+        else {
+            release = await deps.publication.getRelease(origin.releaseId);
             if (release === undefined)
                 return fail(404);
-            if (request.ticket !== undefined) {
-                if (request.actorId === undefined || request.actorId.length === 0)
-                    return fail(401);
-                try {
-                    await deps.tickets.redeem(request.ticket, {
-                        subjectId: request.actorId, artifactId, releaseId: release.releaseId, channel: origin.kind,
-                    });
-                }
-                catch {
-                    return fail(401);
-                }
-                if (!(await canReadNow(artifactId, request.actorId)))
-                    return fail(404);
-                const token = deps.grants.issue({
-                    subjectId: request.actorId,
-                    artifactId,
-                    releaseId: release.releaseId,
+            const owner = JSON.parse(release.manifest).artifactId;
+            if (typeof owner !== 'string')
+                return fail(404);
+            artifactId = owner;
+        }
+        if (release === undefined)
+            return fail(404);
+        if (request.ticket !== undefined) {
+            if (request.actorId === undefined || request.actorId.length === 0)
+                return fail(401);
+            try {
+                await deps.tickets.redeem(request.ticket, {
+                    subjectId: request.actorId, artifactId, releaseId: release.releaseId, channel: origin.kind,
                 });
-                return {
-                    status: 200,
-                    headers: {
-                        'content-type': 'application/json',
-                        'set-cookie': grantCookie(token, CONTENT_GRANT_TTL_SECONDS),
-                    },
-                    body: { activated: true, artifactId, releaseId: release.releaseId },
-                };
             }
-            const token = parseGrantCookie(request.cookie);
-            if (token === undefined)
+            catch {
                 return fail(401);
-            let claims;
+            }
+            if (!(await canReadNow(artifactId, request.actorId)))
+                return fail(404);
+            const token = deps.grants.issue({
+                subjectId: request.actorId,
+                artifactId,
+                releaseId: release.releaseId,
+            });
+            return jsonResponse(200, { activated: true, artifactId, releaseId: release.releaseId }, {
+                'set-cookie': grantCookie(token, CONTENT_GRANT_TTL_SECONDS),
+            });
+        }
+        const token = parseGrantCookie(request.cookie);
+        if (token === undefined)
+            return fail(401);
+        let claims;
+        try {
+            claims = deps.grants.verify(token);
+        }
+        catch {
+            return fail(401);
+        }
+        if (claims.artifactId !== artifactId || claims.releaseId !== release.releaseId) {
+            return fail(401); // fresh version consent: activate this release
+        }
+        if (request.actorId !== undefined && request.actorId !== claims.subjectId)
+            return fail(401);
+        if (!(await canReadNow(artifactId, claims.subjectId)))
+            return fail(404);
+        const filePath = resolveContentPath(request.path);
+        if (filePath === undefined || isServiceWorkerPath(filePath))
+            return fail(404);
+        return serveFile(artifactId, release.manifest, filePath);
+    }
+    return {
+        async handle(request) {
+            let response;
             try {
-                claims = deps.grants.verify(token);
+                response = await handle(request);
             }
             catch {
-                return fail(401);
+                response = fail(500);
             }
-            if (claims.artifactId !== artifactId || claims.releaseId !== release.releaseId) {
-                return fail(401); // fresh version consent: activate this release
+            if (request.method === 'HEAD') {
+                const { bytes: _bytes, body: _body, ...head } = response;
+                return head;
             }
-            if (request.actorId !== undefined && request.actorId !== claims.subjectId)
-                return fail(401);
-            if (!(await canReadNow(artifactId, claims.subjectId)))
-                return fail(404);
-            const filePath = resolveContentPath(request.path);
-            if (filePath === undefined || isServiceWorkerPath(filePath))
-                return fail(404);
-            return serveFile(artifactId, release.manifest, filePath);
+            return response;
         },
     };
 }

package/dist/http.d.ts

@@ -1,45 +1,58 @@
-import type { ParameterSchema } from './parameters.js';
-import type { ArtifactService } from './server/service.js';
-import type { PublicationBlobStore, PublicationService } from './server/publication.js';
+import { type CompiledArtifactsProfile } from './profile/index.js';
+import { type ArtifactKeyDerivationBinding } from './server/command-identity.js';
+import { type GuardedEnsureHost } from './server/service.js';
+import type { KvPort } from './server/ports.js';
+import { type GuardedPublicationDeps, type PublicationService } from './server/publication.js';
+import type { AclStore } from './server/access.js';
 import type { LifecycleService } from './server/lifecycle.js';
-import type { ForkService } from './server/fork.js';
-import { type AclStore } from './server/access.js';
-import { type SourceStore } from './server/sources.js';
-import type { StagingStore, UploadService } from './server/uploads.js';
-import type { TemplateCatalogPort } from './server/templates.js';
+import { type ArtifactInvocationContext, type ArtifactCommitCoordinator } from './server/commit/types.js';
+import { type ArtifactOutcome } from './server/failures.js';
+export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 export interface HttpRequest {
     method: string;
     path: string;
     body: unknown;
     actorId: string;
+    /** Trusted host assertion, never caller authority. */
+    storageScopeId?: string;
+    /** Optional platform envelope; must equal the tool argument byte for byte. */
+    idempotencyKey?: string;
 }
 export interface HttpResponse {
     status: number;
     body: unknown;
 }
+/** Stable content-route error codes; private driver messages never leave the host. */
+export declare function errorBody(status: number): {
+    error: string;
+};
 export interface HttpAppDeps {
-    parameterSchema: ParameterSchema;
-    artifacts: ArtifactService;
-    publication: PublicationService;
-    lifecycle: LifecycleService;
-    forks: ForkService;
+    profile: CompiledArtifactsProfile;
+    coordinator: ArtifactCommitCoordinator;
+    derivation: ArtifactKeyDerivationBinding;
+    /** Explicit pilot-state inventory reader; supply an empty reader only for a verified fresh store. */
+    legacyRecords: Pick<KvPort, 'get'>;
+    ensureHost: GuardedEnsureHost;
+    publication: Omit<GuardedPublicationDeps, 'coordinator' | 'limits'> & {
+        getCurrent: PublicationService['getCurrent'];
+    };
     acls: AclStore;
-    sources: SourceStore;
-    blobs: PublicationBlobStore;
+    lifecycle: Pick<LifecycleService, 'stateOf' | 'canRead'>;
     isApprovedAccount?: (principalId: string) => boolean;
-    /** Bounded upload sessions (L-5e); upload routes refuse when unwired. */
-    uploads?: UploadService;
-    staging?: StagingStore;
-    /** Template kit + API guide catalog (L-5e); refuses when unwired. */
-    templates?: TemplateCatalogPort;
+    /** One trusted URL policy shared by HTTP and MCP receipts. */
+    publicationUrls?: (artifactId: string, releaseId: string) => {
+        stableUrl: string;
+        pinnedUrl: string;
+    };
 }
-/** Stable error body for one status; internal messages never leave the app. */
-export declare function errorBody(status: number): {
-    error: string;
-};
-/** Canonical text MIME types; parameters are omitted (encoding is always UTF-8). */
+export interface ArtifactApp {
+    readonly selectedCapabilities: CompiledArtifactsProfile['selectedCapabilities'];
+    readonly profileDigest: string;
+    execute(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<ArtifactOutcome<HttpResponse>>;
+    handle(request: HttpRequest, invocation: ArtifactInvocationContext): Promise<HttpResponse>;
+}
+/** Retained for consumers describing canonical textual publication inputs. */
 export declare const TEXT_MIME_PATTERN = "^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])";
-/** Create the HTTP app over injected services (no server, no fetch). */
-export declare function createHttpArtifactApp(deps: HttpAppDeps): {
-    handle(request: HttpRequest): Promise<HttpResponse>;
-};
+/** Other mutation surfaces need their own qualification before host activation. */
+export declare function assertArtifactsTransportProfile(value: unknown): asserts value is CompiledArtifactsProfile;
+export declare function createHttpArtifactApp(deps: HttpAppDeps): ArtifactApp;