@sentropic/artifacts 0.2.0 → 0.2.2

package/README.md

@@ -1,5 +1,35 @@
 # @sentropic/artifacts — generic artifact contracts (L-5a)
 
+Version 0.2.1 fixes host commit authorization being masked by the built-in
+publication guard and wires the optional trusted `mapHostError` dependency.
+Publication retains its lifecycle, ACL and policy revision checks; the host
+`authorizeCommit` binding decides account approval and its sanitized refusal code.
+Custom services using `createGuardedPublicationService` may pass the request-bound
+`authorizeCommit` in `publishFinalized(input)`. It runs after
+lifecycle, ACL and policy revision checks. When omitted, publication keeps the
+default `participant.checkApproval` check and denies unapproved or expired commits.
+
+Bind the same mapper on `createHttpArtifactApp`, `createArtifactsToolExecutor`
+(or `createArtifactsAdapter`) and `createArtifactCommitCoordinator` so host wrapper
+errors are classified at their originating layer. For example:
+
+```ts
+import { ArtifactOperationError, type ArtifactHostFailureMapper }
+  from '@sentropic/artifacts/server/outcome-contract';
+
+const mapHostError: ArtifactHostFailureMapper = cause => {
+  const code = (cause as { code?: string } | null)?.code;
+  return code === 'artifact_s3_timeout' || code === 'artifact_connection_lost'
+    ? new ArtifactOperationError('provider_unavailable', { cause }) : undefined;
+};
+```
+
+Pass `{ ...existingOptions, mapHostError }` to each construction. The packed
+`examples/radar-commit-setup.ts` also accepts this option. Unrecognized failures
+keep their existing classification; private causes never enter HTTP/MCP results.
+Frozen contracts, command identity and selected tools remain unchanged.
+
+
 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.

package/dist/adapters/s3.js

@@ -10,6 +10,7 @@
  * host and injected — this module never reads env or creates connections.
  */
 import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, } from '@aws-sdk/client-s3';
+import { assertBlobPrefix } from '../server/blob-prefix.js';
 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) {
@@ -17,12 +18,6 @@ function assertBlobKey(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 {
@@ -49,7 +44,7 @@ export function createS3BlobStore(options) {
             }
         },
         async listKeys(prefix) {
-            assertPrefix(prefix);
+            assertBlobPrefix(prefix);
             const keys = [];
             let token;
             do {

package/dist/http.d.ts

@@ -6,7 +6,7 @@ import { type GuardedPublicationDeps, type PublicationService } from './server/p
 import type { AclStore } from './server/access.js';
 import type { LifecycleService } from './server/lifecycle.js';
 import { type ArtifactInvocationContext, type ArtifactCommitCoordinator } from './server/commit/types.js';
-import { type ArtifactOutcome } from './server/failures.js';
+import { type ArtifactOutcome, type ArtifactHostFailureMapper } from './server/failures.js';
 export { projectArtifactHttpOutcome } from './server/outcome-projection.js';
 export interface HttpRequest {
     method: string;
@@ -27,6 +27,8 @@ export declare function errorBody(status: number): {
     error: string;
 };
 export interface HttpAppDeps {
+    /** Trusted mapping of host wrapper errors; causes remain private. Also bind on the coordinator. */
+    mapHostError?: ArtifactHostFailureMapper;
     profile: CompiledArtifactsProfile;
     coordinator: ArtifactCommitCoordinator;
     derivation: ArtifactKeyDerivationBinding;

package/dist/http.js

@@ -110,25 +110,15 @@ export function createHttpArtifactApp(deps) {
                     const acl = await visible(artifactId, invocation);
                     if (acl.ownerId !== invocation.actorId)
                         throw new ArtifactOperationError('access_denied');
-                    // Both finalization and fresh replay combine provider checks with this request's host guard.
-                    const bindGuard = (request) => ({ ...request,
-                        guard: async (context, transaction) => {
-                            const decision = await request.guard(context, transaction);
-                            return decision.allowed ? invocation.authorizeCommit(context, transaction) : decision;
-                        } });
-                    const coordinator = {
-                        ...deps.coordinator,
-                        finalizePrepared: (request) => deps.coordinator.finalizePrepared(bindGuard(request)),
-                        replayPrepared: (request) => deps.coordinator.replayPrepared(bindGuard(request)),
-                    };
                     const limits = profile.operations.find((entry) => entry.operation === 'publish').limits;
-                    const publication = createGuardedPublicationService({ ...deps.publication, coordinator,
+                    const publication = createGuardedPublicationService({ ...deps.publication, coordinator: deps.coordinator,
                         limits: { maxFiles: limits.publishFilesMax, maxFileBytes: limits.maxDecodedFileBytes,
                             maxTotalBytes: limits.maxDecodedTotalBytes } });
                     const outcome = await publication.publishFinalized({
                         ownerId: acl.ownerId, storageScopeId: invocation.storageScopeId, artifactId,
                         identity: command.identity, actorId: invocation.actorId, invocationId: invocation.invocationId,
                         attemptId: invocation.invocationId, policyRevision: await deps.ensureHost.readPolicyRevision(),
+                        authorizeCommit: invocation.authorizeCommit,
                         source: { kind: 'inline-original' }, profile: normalized.profile,
                         files: normalized.files.map((file) => ({
                             path: file.path, mimeType: file.mimeType, bytes: Uint8Array.from(file.bytes),
@@ -178,7 +168,7 @@ export function createHttpArtifactApp(deps) {
             catch (cause) {
                 const failure = classifyArtifactFailure(cause, { invocationId: invocation?.invocationId ?? '',
                     operation, phase, commitState }, (error) => error instanceof ArtifactProfileInputError
-                    ? new ArtifactOperationError(error.category) : undefined);
+                    ? new ArtifactOperationError(error.category) : deps.mapHostError?.(error));
                 if (cause instanceof CommitQuarantineError) {
                     const migration = { ...failure, kind: 'operational', category: 'provider_unavailable',
                         variant: 'legacy_quarantine', httpStatus: 503, publicCode: 'capability_unavailable', retriable: false };

package/dist/mcp-core.d.ts

@@ -4,13 +4,13 @@ import type { ProviderParameterSchema } from '@sentropic/mcp-platform/registry';
 import type { ArtifactApp, HttpResponse } from './http.js';
 import { type CompiledArtifactsProfile } from './profile/index.js';
 import type { ArtifactInvocationContext } from './server/commit/types.js';
-import { type ArtifactOutcome } from './server/failures.js';
+import { type ArtifactOutcome, type ArtifactHostFailureMapper } from './server/failures.js';
 export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export type { ArtifactKeyDerivationBinding } from './server/command-identity.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.0";
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.2.2";
 export declare const ARTIFACTS_TOOL_NAMES: readonly ["artifacts_get_template", "artifacts_get_api_guide", "artifacts_ensure", "artifacts_publish", "artifacts_create_upload", "artifacts_commit_upload", "artifacts_list", "artifacts_get", "artifacts_get_source", "artifacts_fork", "artifacts_set_access", "artifacts_promote", "artifacts_renew", "artifacts_delete", "artifacts_restore"];
 export type ArtifactsToolName = (typeof ARTIFACTS_TOOL_NAMES)[number];
 export declare const ARTIFACTS_TOOL_SPECS: {
@@ -40,11 +40,14 @@ export interface ArtifactsInvokeInput {
 export declare function createArtifactsToolExecutor(deps: {
     app: ArtifactsApp;
     profile: CompiledArtifactsProfile;
+    mapHostError?: ArtifactHostFailureMapper;
 }): {
     execute: (input: ArtifactsInvokeInput) => Promise<ArtifactOutcome<HttpResponse>>;
     invoke(input: ArtifactsInvokeInput): Promise<HttpResponse>;
 };
 export interface ArtifactsAdapterOptions extends ArtifactsManifestOptions {
+    /** Trusted mapping for failures in the MCP host binding. */
+    mapHostError?: ArtifactHostFailureMapper;
     app: ArtifactsApp;
     /** Bind verified principal/scope and request authorization in trusted host code. */
     createInvocation(request: AppToolInvocation): ArtifactInvocationContext | Promise<ArtifactInvocationContext>;

package/dist/mcp-core.js

@@ -6,7 +6,7 @@ export * from './profile/index.js';
 export { createRadarKeyDerivation } from './server/command-identity.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.2.0';
+export const ARTIFACTS_PROVIDER_VERSION = '0.2.2';
 export const ARTIFACTS_TOOL_NAMES = ARTIFACT_CAPABILITY_NAMES;
 export const ARTIFACTS_TOOL_SPECS = ARTIFACTS_TOOL_NAMES.map((name) => ({ name,
     description: `Artifacts ${name.slice('artifacts_'.length).replaceAll('_', ' ')}.`,
@@ -36,9 +36,9 @@ export function createArtifactsManifest(options) {
         audit: { eventKinds: ['invoke'], artifactsProfileDigest: profile.profileDigest }, durability: {},
     };
 }
-function rejected(cause, invocationId, operation) {
+function rejected(cause, invocationId, operation, mapHostError) {
     return { ok: false, failure: classifyArtifactFailure(cause, { invocationId, operation,
-            phase: cause instanceof ArtifactProfileInputError ? cause.phase : 'entry', commitState: 'not_committed' }, (error) => error instanceof ArtifactProfileInputError ? new ArtifactOperationError(error.category) : undefined) };
+            phase: cause instanceof ArtifactProfileInputError ? cause.phase : 'entry', commitState: 'not_committed' }, (error) => error instanceof ArtifactProfileInputError ? new ArtifactOperationError(error.category) : mapHostError?.(error)) };
 }
 export function createArtifactsToolExecutor(deps) {
     assertArtifactsTransportProfile(deps.profile);
@@ -70,7 +70,7 @@ export function createArtifactsToolExecutor(deps) {
                 storageScopeId: input.invocation.storageScopeId, idempotencyKey: input.idempotencyKey }, input.invocation);
         }
         catch (cause) {
-            return rejected(cause, input.invocation?.invocationId ?? '', input.tool);
+            return rejected(cause, input.invocation?.invocationId ?? '', input.tool, deps.mapHostError);
         }
     }
     return { execute, async invoke(input) {
@@ -100,7 +100,7 @@ export function createArtifactsAdapter(options) {
                     invocation, idempotencyKey: request.idempotencyKey });
             }
             catch (cause) {
-                outcome = rejected(cause, request.ctx.requestId, request.capabilityRef);
+                outcome = rejected(cause, request.ctx.requestId, request.capabilityRef, options.mapHostError);
             }
             return projectArtifactMcpOutcome(outcome, request.ctx.auditId);
         },

package/dist/server/blob-prefix.d.ts

@@ -0,0 +1,2 @@
+/** Reject empty or escaping prefixes before enumeration or external I/O. */
+export declare function assertBlobPrefix(prefix: string): void;

package/dist/server/blob-prefix.js

@@ -0,0 +1,14 @@
+import { ArtifactOperationError } from './failures.js';
+class InvalidBlobPrefixError extends ArtifactOperationError {
+    code = 'invalid_blob_prefix';
+    constructor(prefix) {
+        super('invalid_request');
+        this.message = `invalid blob prefix: ${prefix}`;
+    }
+}
+/** Reject empty or escaping prefixes before enumeration or external I/O. */
+export function assertBlobPrefix(prefix) {
+    if (prefix.length === 0 || prefix.includes('..')) {
+        throw new InvalidBlobPrefixError(prefix);
+    }
+}

package/dist/server/commit/coordinator.js

@@ -59,10 +59,10 @@ const isConnectionLoss = (error) => {
 const LOCK_TIMEOUT_CODE = '55P03';
 /** Serialization/deadlock/cancel outcomes: retriable unavailability (r2 E3/P2-2). */
 const RETRIABLE_SQLSTATES = new Set(['40001', '40P01', '57014']);
-const classifyOperational = (request, phase, commitState, error) => {
+const classifyOperational = (request, phase, commitState, error, mapHostError) => {
     const classified = classifyArtifactFailure(error, {
         invocationId: request.invocationId, operation: request.operation, phase, commitState,
-    });
+    }, mapHostError);
     if (classified.kind === 'operational')
         return classified;
     return failure('provider_error', request, phase, commitState, error, { variant: 'unclassified' });
@@ -227,7 +227,7 @@ export function createArtifactCommitCoordinator(options) {
         const code = typeof error === 'object' && error !== null
             ? error.code : undefined;
         if (settleError === undefined && typeof code === 'string' && RETRIABLE_SQLSTATES.has(code)) {
-            return { ok: false, failure: classifyOperational(request, 'commit', 'not_committed', error) };
+            return { ok: false, failure: classifyOperational(request, 'commit', 'not_committed', error, options.mapHostError) };
         }
         return unknownOutcome(request, 'commit', settleError === undefined ? error : { commit: error, settlement: settleError });
     };
@@ -374,7 +374,7 @@ export function createArtifactCommitCoordinator(options) {
             await abandon(request);
             return {
                 ok: false,
-                failure: classifyOperational(request, phase, 'not_committed', error),
+                failure: classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
             };
         }
         const settle = trackSettlement(connection);
@@ -423,7 +423,7 @@ export function createArtifactCommitCoordinator(options) {
             }
             return {
                 ok: false,
-                failure: classifyOperational(request, phase, 'not_committed', error),
+                failure: classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
             };
         }
     };
@@ -484,7 +484,7 @@ export function createArtifactCommitCoordinator(options) {
                     ok: false,
                     failure: isConnectionLoss(error)
                         ? failure('provider_unavailable', request, phase, 'not_committed', error)
-                        : classifyOperational(request, phase, 'not_committed', error),
+                        : classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
                 };
             }
             const active = connection;
@@ -613,7 +613,7 @@ export function createArtifactCommitCoordinator(options) {
                 }
                 return {
                     ok: false,
-                    failure: classifyOperational(request, phase, 'not_committed', error),
+                    failure: classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
                 };
             }
         },
@@ -630,7 +630,7 @@ export function createArtifactCommitCoordinator(options) {
                 await abandon(request);
                 return {
                     ok: false,
-                    failure: classifyOperational(request, phase, 'not_committed', error),
+                    failure: classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
                 };
             }
             const active = connection;
@@ -720,7 +720,7 @@ export function createArtifactCommitCoordinator(options) {
                 }
                 return {
                     ok: false,
-                    failure: classifyOperational(request, phase, 'not_committed', error),
+                    failure: classifyOperational(request, phase, 'not_committed', error, options.mapHostError),
                 };
             }
         },

package/dist/server/commit/types.d.ts

@@ -13,6 +13,7 @@
  */
 import type { CommitArrivalObserver, CommitBarrierObserver, CommitBarrierPoint } from '../../testing.js';
 import type { commitFenceBrand, commitTransactionBrand } from './brands.js';
+import type { ArtifactHostFailureMapper } from '../failures.js';
 /** Version of the frozen command-codec shape (r2 C6). */
 export declare const COMMAND_CODEC_VERSION: "artifacts-command/v1";
 /** Server-derived internal key: distinct from any caller key. */
@@ -302,6 +303,8 @@ export type ArtifactOutcome<T> = {
 export type FinalizeResult = ArtifactOutcome<StoredCommitReceipt>;
 /** Coordinator construction options. */
 export interface CommitCoordinatorOptions {
+    /** Trusted host wrapper classification for failures inside the atomic unit. */
+    readonly mapHostError?: ArtifactHostFailureMapper;
     readonly executor: CommitExecutor;
     readonly policy: CommitPolicyParticipantFactory;
     /** Trusted domain adapters; every call resolves fresh state, including replay. */

package/dist/server/publication.d.ts

@@ -7,7 +7,7 @@ import type { ArtifactAcl } from './access.js';
 import type { ArtifactState } from './lifecycle.js';
 import { type RefcountStore } from './gc.js';
 import type { CommandIdentity } from './command-identity.js';
-import type { CommitLockFn, ArtifactCommitCoordinator, FinalizeResult, FinalizeTxClient } from './commit/types.js';
+import type { AuthorizeCommit, CommitLockFn, ArtifactCommitCoordinator, FinalizeResult, FinalizeTxClient } from './commit/types.js';
 export { DEFAULT_PUBLICATION_LIMITS, type PublicationLimits } from './publication-limits.js';
 export interface ReleaseRecord {
     releaseId: string;
@@ -127,6 +127,8 @@ export interface GuardedPublishInput extends PublishInput {
     readonly identity: CommandIdentity;
     readonly actorId: string;
     readonly policyRevision: string;
+    /** Request-bound host approval guard; defaults to participant.checkApproval. */
+    readonly authorizeCommit?: AuthorizeCommit;
     readonly callerKey?: string;
     readonly attemptId?: string;
     readonly invocationId?: string;

package/dist/server/publication.js

@@ -12,6 +12,7 @@
  * serve unit tests and the Postgres/S3 adapters serve integration.
  */
 import { createHash } from 'node:crypto';
+import { assertBlobPrefix } from './blob-prefix.js';
 import { canonicalManifest, manifestDigest } from '../codecs.js';
 import { parseSourceRef } from './sources.js';
 import { publicationLimits, validatePublicationFiles } from './publication-limits.js';
@@ -59,8 +60,9 @@ export function createMemoryBlobStore() {
         getBlob(key) {
             return Promise.resolve(blobs.get(key));
         },
-        listKeys(prefix) {
-            return Promise.resolve([...blobs.keys()].filter((key) => key.startsWith(prefix)).sort());
+        async listKeys(prefix) {
+            assertBlobPrefix(prefix);
+            return [...blobs.keys()].filter((key) => key.startsWith(prefix)).sort();
         },
         deleteBlob(key) {
             if (!blobs.has(key))
@@ -247,7 +249,7 @@ export function createGuardedPublicationService(deps) {
     const cleanupWindowMs = deps.cleanupWindowMs ?? DEFAULT_CLEANUP_WINDOW_MS;
     if (!Number.isSafeInteger(cleanupWindowMs) || cleanupWindowMs < 1)
         throw new Error('invalid preparation lifetime');
-    const guard = (client) => async (context, transaction) => {
+    const guard = (client, authorizeCommit) => async (context, transaction) => {
         const { state, acl } = await deps.createUnitWriter(client()).readAuthorization(context.artifactId);
         const verdict = decidePublishAuthorization({ lifecycleState: state, acl, actorId: context.actorId });
         if (!verdict.allowed) {
@@ -259,19 +261,6 @@ export function createGuardedPublicationService(deps) {
                 retriable: false,
             };
         }
-        const approval = await transaction.participant.checkApproval({
-            actorId: context.actorId,
-            operation: context.operation,
-        });
-        if (!approval.approved) {
-            return {
-                allowed: false,
-                reason: approval.reason ?? 'denied',
-                publicCode: 'access_denied',
-                status: 403,
-                retriable: false,
-            };
-        }
         const revision = await transaction.participant.readRevision();
         if (revision !== context.policyRevision) {
             return {
@@ -282,6 +271,12 @@ export function createGuardedPublicationService(deps) {
                 retriable: false,
             };
         }
+        if (authorizeCommit !== undefined)
+            return authorizeCommit(context, transaction);
+        const approval = await transaction.participant.checkApproval({ actorId: context.actorId, operation: context.operation });
+        if (!approval.approved) {
+            return { allowed: false, reason: approval.reason ?? 'denied', publicCode: 'access_denied', status: 403, retriable: false };
+        }
         return { allowed: true, fence: transaction.participant.mintFence(revision, context.invocationId) };
     };
     return {
@@ -365,7 +360,7 @@ export function createGuardedPublicationService(deps) {
                         if (finalizationClient === undefined)
                             throw new Error('publication guard needs the finalization client');
                         return finalizationClient;
-                    }),
+                    }, input.authorizeCommit),
                     finishIntents: async (client) => {
                         await deps.createUnitWriter(client).completeIntent(intent.intentId);
                     },

package/docs/migration-l6.md

@@ -83,7 +83,12 @@ under this lock and compares it to the stored receipt. Missing or changed
 targets deny before the host guard; explicit replay requires a binding.
 
 Use `createGuardedEnsureService` and `createGuardedPublicationService` for
-custom services. The canonical coordinator exposes `finalizeOperation` and
+custom services. Pass the request-bound host guard as `publishFinalized(input)`'s
+optional `authorizeCommit` field to preserve host approval policy and refusal codes;
+it runs after lifecycle, ACL and policy revision checks. When omitted, publication
+uses `participant.checkApproval` and denies unapproved or expired commits.
+HTTP/MCP pass the invocation's host guard automatically.
+The canonical coordinator exposes `finalizeOperation` and
 `replayOperation` with the frozen L0 inputs. Bind fresh domain request plans
 through its `operations` option; no process-local replay cache is used.
 Provider adapters use `finalizePrepared` and `replayPrepared` on that same

package/examples/radar-commit-setup.ts

@@ -206,12 +206,15 @@ export function createRadarCommitSetup(options: {
   pool: Pool;
   clock: { nowMs: number };
   quotaKey?: string;
+  /** Bind this same mapper on createHttpArtifactApp and createArtifactsAdapter. */
+  mapHostError?: CommitCoordinatorOptions['mapHostError'];
   testObserver?: CommitCoordinatorOptions['testObserver'];
   testPoints?: readonly CoordinatorTestPoint[];
 }): RadarCommitSetup {
   const quotaKey = options.quotaKey ?? 'radar-quota';
   const abandonedAttempts: AbandonedAttempt[] = [];
   const coordinator = createArtifactCommitCoordinator({
+    mapHostError: options.mapHostError,
     executor: createPostgresCommitExecutor(options.pool),
     policy: createParticipantFactory(quotaKey, options.clock),
     nowMs: () => options.clock.nowMs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9).",
   "type": "module",
   "license": "MIT",