@sentropic/artifacts 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,8 @@
 
 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).
+`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).
 
 ## What's here (L-5a)
 
@@ -48,6 +49,79 @@ make test-artifacts-integration API_PORT=9550 UI_PORT=5750 MAILDEV_UI_PORT=1650
 
 No Immo defaults, URLs or bindings in generic source.
 
+## Storage adapters and host migrations
+
+Hosts import `createS3BlobStore` from `@sentropic/artifacts/adapters/s3`
+and `createPostgresArtifactStore` from `@sentropic/artifacts/adapters/postgres`.
+Install the optional peer `@aws-sdk/client-s3@^3.980.0` for S3 and
+`pg@^8.12.0` for Postgres (`@types/pg` for TypeScript hosts). Pass a configured
+`S3Client` and bucket to the S3 adapter and a `pg.Pool` to the Postgres adapter.
+The core works without either driver; adapters do not create connections or
+apply DDL at import or startup.
+
+The installed package includes SQL resources exported under
+`@sentropic/artifacts/migrations/*`. Read them through Node's resolver:
+
+```js
+import { readFile } from 'node:fs/promises';
+
+const migrations = ['0001_artifacts.sql', '0002_lifecycle.sql'];
+for (const name of migrations) {
+  const sql = await readFile(new URL(import.meta.resolve(
+    `@sentropic/artifacts/migrations/${name}`,
+  )), 'utf8');
+  // Hand each SQL resource to the host's existing journaled migration runner.
+}
+```
+
+Apply `0001_artifacts.sql` first to create the domain schema, then
+`0002_lifecycle.sql` to add lifecycle, sharing, sources and GC support, before
+using the Postgres store. The host owns migration credentials, serialization,
+transactions and the migration journal; execute each version through that
+runner rather than running this read loop at application startup.
+
+Before the first `/ensure` or `artifacts_ensure`, the host must provision an
+`artifacts.storage_scopes` row for each storage scope it uses. Migration 0001
+creates the table but does not seed it; the package neither provisions scopes
+nor infers their organization. The artifact's `storage_scope_id` references
+this row through a foreign key. For example, run a parameterized host query:
+
+```js
+await pool.query(
+  'INSERT INTO artifacts.storage_scopes (id, org_id) VALUES ($1, $2) ON CONFLICT (id) DO NOTHING',
+  [storageScopeId, organizationId],
+);
+```
+
+Keep the scope ID stable, validate that any existing row belongs to the intended
+organization, and use that ID as `storageScopeId` (or MCP's configured
+`defaultStorageScopeId`). The host owns provisioning permissions and tenant
+authorization; changing a binding or organization identifier does not provision
+a scope automatically.
+
+## Inline publication: text or bytes
+
+Each file in HTTP `POST /publish` and MCP `artifacts_publish` accepts exactly
+one of `text` (a string, including the empty string) or `bytes` (integers 0–255).
+The server encodes `text` as UTF-8 before calculating digests and byte sizes:
+
+```json
+{
+  "artifactId": "<ensured artifact UUID>",
+  "files": [{ "path": "index.html", "mimeType": "text/html", "text": "<h1>Été à Montréal 🏠</h1>" }]
+}
+```
+
+`text` requires a canonical lowercase MIME type without parameters: `text/*`,
+`application/javascript`, `application/ecmascript`, `application/json`,
+`application/xml`, `application/*+json`, `application/*+xml`, or `image/svg+xml`.
+Use `bytes` for binary formats such as PNG or PDF. Both fields together, neither
+field, a non-string `text`, or a non-text MIME type with `text` are rejected.
+
+Content responses include `Cross-Origin-Resource-Policy: same-origin`, preventing
+cross-origin no-CORS resource embedding even between sibling subdomains sharing
+a registrable domain. Assets within the same artifact origin remain loadable.
+
 ## What's here (L-5d–5e)
 
 - `src/content/grants.ts` — 55s HMAC content grants (60s cutoff budget) and

package/dist/content/headers.js

@@ -31,6 +31,7 @@ export function contentHeaders(input) {
         'content-type': withCharset,
         'content-length': String(input.size),
         'x-content-type-options': 'nosniff',
+        'cross-origin-resource-policy': 'same-origin',
         'cache-control': cacheable ? `private, max-age=${input.assetCacheSeconds}` : 'no-store',
         'x-frame-options': 'DENY',
         'referrer-policy': 'no-referrer',

package/dist/http.d.ts

@@ -37,6 +37,8 @@ export interface HttpAppDeps {
 export declare function errorBody(status: number): {
     error: string;
 };
+/** Canonical text MIME types; parameters are omitted (encoding is always UTF-8). */
+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>;

package/dist/http.js

@@ -84,6 +84,20 @@ function needBytes(value) {
     }
     return bytes;
 }
+/** Canonical text MIME types; parameters are omitted (encoding is always UTF-8). */
+export const TEXT_MIME_PATTERN = '^(?:text/[a-z0-9!#$&^_.+-]+|application/(?:javascript|ecmascript|json|xml|[a-z0-9!#$&^_.+-]+\\+(?:json|xml))|image/svg\\+xml)(?![\\s\\S])';
+function needFileBytes(entry, mimeType) {
+    const hasBytes = 'bytes' in entry;
+    const hasText = 'text' in entry;
+    if (hasBytes === hasText)
+        throw new Error('invalid file: supply exactly one of bytes or text');
+    if (hasBytes)
+        return needBytes(entry['bytes']);
+    if (typeof entry['text'] !== 'string' || !new RegExp(TEXT_MIME_PATTERN).test(mimeType)) {
+        throw new Error('invalid file text: expected a string and a canonical text MIME type');
+    }
+    return new TextEncoder().encode(entry['text']);
+}
 /** Create the HTTP app over injected services (no server, no fetch). */
 export function createHttpArtifactApp(deps) {
     const isApproved = deps.isApprovedAccount ?? (() => false);
@@ -177,10 +191,11 @@ export function createHttpArtifactApp(deps) {
                         throw new Error('invalid request: missing files');
                     const files = rawFiles.map((file) => {
                         const entry = needObject(file);
+                        const mimeType = needString(entry['mimeType'], 'file.mimeType');
                         return {
                             path: needString(entry['path'], 'file.path'),
-                            mimeType: needString(entry['mimeType'], 'file.mimeType'),
-                            bytes: needBytes(entry['bytes']),
+                            mimeType,
+                            bytes: needFileBytes(entry, mimeType),
                         };
                     });
                     const source = body['source'];

package/dist/mcp.d.ts

@@ -14,7 +14,7 @@ import type { ProviderParameterSchema, RegistryDefinition } from '@sentropic/mcp
 import type { HttpRequest, HttpResponse } from './http.js';
 export declare const ARTIFACTS_PROVIDER_ID = "sentropic.artifacts";
 export declare const ARTIFACTS_APP_ID = "sentropic-artifacts";
-export declare const ARTIFACTS_PROVIDER_VERSION = "0.1.0";
+export declare const ARTIFACTS_PROVIDER_VERSION = "0.1.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];
 type Schema = Record<string, unknown>;

package/dist/mcp.js

@@ -1,7 +1,8 @@
 import { computeManifestDigest } from '@sentropic/mcp-platform/tool-configuration';
+import { TEXT_MIME_PATTERN } from './http.js';
 export const ARTIFACTS_PROVIDER_ID = 'sentropic.artifacts';
 export const ARTIFACTS_APP_ID = 'sentropic-artifacts';
-export const ARTIFACTS_PROVIDER_VERSION = '0.1.0';
+export const ARTIFACTS_PROVIDER_VERSION = '0.1.2';
 export const ARTIFACTS_TOOL_NAMES = [
     'artifacts_get_template', 'artifacts_get_api_guide', 'artifacts_ensure',
     'artifacts_publish', 'artifacts_create_upload', 'artifacts_commit_upload',
@@ -21,7 +22,13 @@ const record = {
     additionalProperties: { type: ['string', 'number', 'boolean', 'null'] },
 };
 const fileBytes = { type: 'array', items: int(0, 255) };
-const fileEntry = obj({ path: str, mimeType: str, bytes: fileBytes }, ['path', 'mimeType', 'bytes']);
+const fileEntry = {
+    ...obj({ path: str, mimeType: str, bytes: fileBytes, text: { type: 'string', description: 'UTF-8 text; mutually exclusive with bytes; text MIME types only.' } }, ['path', 'mimeType']),
+    oneOf: [
+        { required: ['bytes'], not: { required: ['text'] } },
+        { required: ['text'], not: { required: ['bytes'] }, properties: { mimeType: { pattern: TEXT_MIME_PATTERN } } },
+    ],
+};
 const sourceRef = obj({
     kind: { type: 'string', enum: ['inline-original', 'base-commit', 'recipe'] },
     commit: { type: 'string' },

package/migrations/0001_artifacts.sql

@@ -0,0 +1,90 @@
+-- L-5b — artifacts domain schema (spec-v8 §9).
+--
+-- Owned by the artifact domain; executed by the Immo host through its
+-- existing migration journal (at most one root-app migration; preferred
+-- Immo-owned adapter). Additive only: no ALTER/DROP of existing objects.
+-- 5b tables: storage scopes, artifacts (stable bindings), releases, current
+-- pointer, blobs, uploads, object intents, idempotency keys. Sharing/access,
+-- lifecycle/GC and hostname reservations arrive with L-5c migrations.
+-- Release states are CHECK-closed to ('ready') in this lot; L-5c extends
+-- the set with its own additive migration.
+
+CREATE SCHEMA IF NOT EXISTS artifacts;
+
+-- Opaque storage scope isolating physical keys from org reindexing.
+CREATE TABLE IF NOT EXISTS artifacts.storage_scopes (
+  id TEXT PRIMARY KEY,
+  org_id TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Artifact with owner-scoped stable binding (one UUID per owner+binding).
+CREATE TABLE IF NOT EXISTS artifacts.artifacts (
+  id UUID PRIMARY KEY,
+  storage_scope_id TEXT NOT NULL REFERENCES artifacts.storage_scopes (id),
+  owner_id TEXT NOT NULL,
+  binding_name TEXT NOT NULL,
+  profile JSONB NOT NULL DEFAULT '{}',
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE (storage_scope_id, owner_id, binding_name)
+);
+
+-- Immutable sealed releases (canonical manifest bytes + digest). The manifest
+-- is TEXT, not JSONB: JSONB key reordering would break byte-identity of the
+-- content-addressed bytes; the digest covers the exact stored bytes.
+CREATE TABLE IF NOT EXISTS artifacts.releases (
+  id UUID PRIMARY KEY,
+  artifact_id UUID NOT NULL REFERENCES artifacts.artifacts (id) ON DELETE CASCADE,
+  manifest_digest TEXT NOT NULL,
+  manifest TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'ready' CHECK (state IN ('ready')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS releases_by_artifact ON artifacts.releases (artifact_id);
+
+-- Current release pointer (CAS-promoted; the loser's release stays orphan).
+CREATE TABLE IF NOT EXISTS artifacts.artifact_current (
+  artifact_id UUID PRIMARY KEY REFERENCES artifacts.artifacts (id) ON DELETE CASCADE,
+  release_id UUID NOT NULL REFERENCES artifacts.releases (id) ON DELETE RESTRICT
+);
+
+-- Addressed blobs (deduplicated by scope+digest; pins arrive in L-5c).
+CREATE TABLE IF NOT EXISTS artifacts.blobs (
+  storage_scope_id TEXT NOT NULL,
+  digest TEXT NOT NULL,
+  size INTEGER NOT NULL CHECK (size >= 0),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (storage_scope_id, digest)
+);
+
+-- Bounded upload sessions (ephemeral staging ledger for GC).
+CREATE TABLE IF NOT EXISTS artifacts.uploads (
+  id UUID PRIMARY KEY,
+  max_size INTEGER NOT NULL CHECK (max_size > 0),
+  size INTEGER NOT NULL DEFAULT 0 CHECK (size >= 0),
+  mime_type TEXT NOT NULL,
+  state TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open', 'committed', 'discarded')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS uploads_by_state ON artifacts.uploads (state);
+
+-- Object intents recorded before every external operation.
+CREATE TABLE IF NOT EXISTS artifacts.object_intents (
+  id UUID PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('commit-release', 'delete-blob', 'promote-release')),
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (state IN ('pending', 'done', 'failed')),
+  payload JSONB NOT NULL DEFAULT '{}',
+  error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS intents_pending ON artifacts.object_intents (state, created_at)
+  WHERE state = 'pending';
+
+-- Operation idempotency: one stored result per key.
+CREATE TABLE IF NOT EXISTS artifacts.idempotency_keys (
+  key TEXT PRIMARY KEY,
+  params_hash TEXT NOT NULL,
+  result JSONB NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);

package/migrations/0002_lifecycle.sql

@@ -0,0 +1,59 @@
+-- L-5c — lifecycle, sharing, sources and GC schema (spec-v8 §9).
+--
+-- Additive upgrade over 0001: no column is dropped or narrowed, existing
+-- rows keep working (defaults preserve 5b semantics: artifacts start
+-- active, releases start ready). `commit` is a reserved word: the source
+-- commit column is named `commit_tx`. Release states widen from ('ready')
+-- to ('ready','retired','purged'); artifact lifecycle, grants, sources and
+-- GC holders/pins are new tables. Sharing grants, lifecycle transitions and
+-- refcounts stay consistent through the Postgres adapter (no api/src
+-- imports); the host applies this file through its existing journal.
+
+-- Artifact lifecycle state + renewal marker + public flag (approved accounts only, never anonymous).
+ALTER TABLE artifacts.artifacts
+  ADD COLUMN IF NOT EXISTS lifecycle_state TEXT NOT NULL DEFAULT 'active'
+    CHECK (lifecycle_state IN ('active', 'withdrawn', 'deleted', 'purged')),
+  ADD COLUMN IF NOT EXISTS renewed_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS is_public BOOLEAN NOT NULL DEFAULT false;
+
+-- Widen release states: ready (committed/current) → retired (supplanted) → purged (cascade).
+ALTER TABLE artifacts.releases DROP CONSTRAINT IF EXISTS releases_state_check;
+ALTER TABLE artifacts.releases
+  ADD CONSTRAINT releases_state_check CHECK (state IN ('ready', 'retired', 'purged'));
+
+-- Sharing grants: exact (artifact, principal) pairs, no wildcards.
+-- (`grant` is reserved in SQL; the column is `permission`, mapped to the
+-- `grant` field by the adapter.)
+CREATE TABLE IF NOT EXISTS artifacts.artifact_access (
+  artifact_id UUID NOT NULL REFERENCES artifacts.artifacts (id) ON DELETE CASCADE,
+  principal_id TEXT NOT NULL,
+  permission TEXT NOT NULL CHECK (permission IN ('read', 'source')),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (artifact_id, principal_id)
+);
+
+-- Explicit source provenance per artifact (recipe/base commit/inline-original marker).
+CREATE TABLE IF NOT EXISTS artifacts.artifact_sources (
+  artifact_id UUID PRIMARY KEY REFERENCES artifacts.artifacts (id) ON DELETE CASCADE,
+  kind TEXT NOT NULL CHECK (kind IN ('inline-original', 'base-commit', 'recipe')),
+  commit_tx TEXT,
+  steps JSONB,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- GC refcount holders: one row per (digest, holder); counts derive by COUNT.
+CREATE TABLE IF NOT EXISTS artifacts.blob_ref_holders (
+  digest TEXT NOT NULL,
+  holder TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (digest, holder)
+);
+CREATE INDEX IF NOT EXISTS ref_holders_by_digest ON artifacts.blob_ref_holders (digest);
+
+-- GC pins: explicit retention against concurrent collection.
+CREATE TABLE IF NOT EXISTS artifacts.blob_pins (
+  digest TEXT NOT NULL,
+  reason TEXT NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+  PRIMARY KEY (digest, reason)
+);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -24,6 +24,15 @@
       "types": "./dist/codecs.d.ts",
       "import": "./dist/codecs.js"
     },
+    "./adapters/s3": {
+      "types": "./dist/adapters/s3.d.ts",
+      "import": "./dist/adapters/s3.js"
+    },
+    "./adapters/postgres": {
+      "types": "./dist/adapters/postgres.d.ts",
+      "import": "./dist/adapters/postgres.js"
+    },
+    "./migrations/*": "./migrations/*",
     "./server/ports": {
       "types": "./dist/server/ports.d.ts",
       "import": "./dist/server/ports.js"
@@ -131,6 +140,7 @@
   },
   "files": [
     "dist",
+    "migrations",
     "README.md",
     "LICENSE"
   ],
@@ -143,21 +153,27 @@
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run tests"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@aws-sdk/client-s3": "^3.980.0",
+    "@sentropic/mcp-platform": ">=0.3.0 <0.5.0",
     "pg": "^8.12.0"
   },
-  "peerDependencies": {
-    "@sentropic/mcp-platform": ">=0.3.0 <0.4.0"
-  },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
     "@sentropic/mcp-platform": {
       "optional": true
+    },
+    "pg": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "^3.980.0",
     "@types/node": "^22.10.10",
     "@types/pg": "^8.15.5",
+    "pg": "^8.12.0",
     "typescript": "5.4.5",
     "vitest": "4.1.0"
   }