@sentropic/artifacts 0.0.0-stage → 0.1.0

package/dist/server/templates.js

@@ -0,0 +1,86 @@
+/**
+ * L-5e — template kit + API guide catalog (spec-v8 §9 5e).
+ *
+ * The generic provider ships a minimal static-web kit and a versioned guide
+ * describing the artifacts_* surface. Hosts inject their own catalog port
+ * (approved template/guide assets); the default catalog carries no
+ * credentials, no host data and no external URLs. A template kit contains
+ * approved sources plus a build recipe — never executable server builds.
+ */
+export const DEFAULT_TEMPLATE_ID = 'static-html';
+export const DEFAULT_API_GUIDE_VERSION = 'v1';
+const INDEX_HTML = [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    '<title>Artifact page</title>',
+    '<link rel="stylesheet" href="./styles.css">',
+    '</head>',
+    '<body>',
+    '<main id="app">',
+    '<h1>Artifact page</h1>',
+    '<p>Static page published with the artifacts provider. Reader data calls',
+    'go through the host reader profile; this kit performs none.</p>',
+    '</main>',
+    '<script src="./app.js"></script>',
+    '</body>',
+    '</html>',
+    '',
+].join('\n');
+const STYLES_CSS = [
+    'body { font-family: system-ui, sans-serif; margin: 2rem; }',
+    'main { max-width: 44rem; }',
+    '',
+].join('\n');
+const APP_JS = [
+    "document.getElementById('app')?.setAttribute('data-ready', 'true');",
+    '',
+].join('\n');
+const GUIDE_V1 = [
+    '# Artifacts API guide v1',
+    '',
+    'Publish and share static web pages through the `artifacts_*` tools:',
+    '',
+    '- `artifacts_get_template` / `artifacts_get_api_guide`: start here.',
+    '- `artifacts_ensure`: resolve (or create) your private artifact view.',
+    '- `artifacts_publish`: publish inline files as a new release.',
+    '- `artifacts_create_upload` + bounded HTTP append +',
+    '  `artifacts_commit_upload`: stage large bytes, then commit them.',
+    '- `artifacts_list` / `artifacts_get` / `artifacts_get_source`: discover.',
+    '- `artifacts_fork`: private independent copy (no ACL copied).',
+    '- `artifacts_set_access`: grant/revoke read or source, toggle public.',
+    '- `artifacts_promote`: explicit version selection (expected-current).',
+    '- `artifacts_renew`, `artifacts_delete`, `artifacts_restore`: lifecycle.',
+    '',
+    'Rules: artifacts are private by default; "public" means approved',
+    'accounts of the host, never anonymous. Source export is a separate',
+    'right. Pages never receive credentials; reader data access goes through',
+    'the host reader profile bound to the artifact and release.',
+    '',
+].join('\n');
+/** Generic in-package catalog; hosts override with approved local assets. */
+export function createDefaultTemplateCatalog() {
+    const template = {
+        templateId: DEFAULT_TEMPLATE_ID,
+        version: 'v1',
+        description: 'Minimal static HTML page kit (no build step, no external calls).',
+        files: [
+            { path: 'index.html', content: INDEX_HTML },
+            { path: 'styles.css', content: STYLES_CSS },
+            { path: 'app.js', content: APP_JS },
+        ],
+        buildRecipe: ['Publish the files as-is with artifacts_publish; no build step.'],
+    };
+    const guide = { version: DEFAULT_API_GUIDE_VERSION, markdown: GUIDE_V1 };
+    return {
+        getTemplate(templateId) {
+            return Promise.resolve(templateId === template.templateId ? template : undefined);
+        },
+        getApiGuide(version) {
+            const wanted = version ?? guide.version;
+            return Promise.resolve(wanted === guide.version ? guide : undefined);
+        },
+    };
+}

package/dist/server/uploads.d.ts

@@ -0,0 +1,29 @@
+export interface BlobRef {
+    digest: string;
+    size: number;
+}
+export interface StagingStore {
+    write(uploadId: string, bytes: Uint8Array): Promise<void>;
+    read(uploadId: string): Promise<Uint8Array>;
+    discard(uploadId: string): Promise<void>;
+}
+/** In-memory StagingStore double for unit tests. */
+export declare function createMemoryStaging(): StagingStore;
+export interface BeginUploadInput {
+    mimeType: string;
+    maxSize?: number;
+}
+export interface UploadServiceOptions {
+    maxUploadBytes: number;
+}
+export interface UploadService {
+    begin(input: BeginUploadInput): Promise<{
+        uploadId: string;
+    }>;
+    append(uploadId: string, offset: number, chunk: Uint8Array): Promise<{
+        size: number;
+    }>;
+    commit(uploadId: string, expected: BlobRef): Promise<BlobRef>;
+}
+/** Create an upload service over an injected staging store (no S3 imports). */
+export declare function createUploadService(staging: StagingStore, options: UploadServiceOptions, ids?: () => string): UploadService;

package/dist/server/uploads.js

@@ -0,0 +1,86 @@
+/**
+ * L-5b — bounded uploads (spec-v8 §9).
+ *
+ * Uploads stage bytes under a bounded prefix with a strict size budget and
+ * sequential offsets. Commit verifies the staged bytes against the declared
+ * SHA-256 digest and size before returning a blob reference; false
+ * hashes/sizes, over-budget appends, out-of-order offsets and any write
+ * after commit are refused fail-closed. Staging is ephemeral: sessions live
+ * in memory and never become visible releases (publication owns durability
+ * via object intents). The byte store is injected; the memory double serves
+ * unit tests and the S3 adapter serves the L-5b integration proof.
+ */
+import { createHash } from 'node:crypto';
+/** In-memory StagingStore double for unit tests. */
+export function createMemoryStaging() {
+    const staged = new Map();
+    return {
+        write(uploadId, bytes) {
+            staged.set(uploadId, bytes);
+            return Promise.resolve();
+        },
+        read(uploadId) {
+            const bytes = staged.get(uploadId);
+            if (bytes === undefined)
+                throw new Error(`unknown upload: ${uploadId}`);
+            return Promise.resolve(bytes);
+        },
+        discard(uploadId) {
+            staged.delete(uploadId);
+            return Promise.resolve();
+        },
+    };
+}
+/** Create an upload service over an injected staging store (no S3 imports). */
+export function createUploadService(staging, options, ids = () => crypto.randomUUID()) {
+    const sessions = new Map();
+    return {
+        async begin(input) {
+            const uploadId = ids();
+            sessions.set(uploadId, {
+                committed: false,
+                maxSize: input.maxSize ?? options.maxUploadBytes,
+                size: 0,
+            });
+            await staging.write(uploadId, new Uint8Array(0));
+            return { uploadId };
+        },
+        async append(uploadId, offset, chunk) {
+            const session = sessions.get(uploadId);
+            if (session === undefined)
+                throw new Error(`unknown upload: ${uploadId}`);
+            if (session.committed)
+                throw new Error(`upload already committed: ${uploadId}`);
+            if (offset !== session.size) {
+                throw new Error(`upload offset mismatch for ${uploadId}: expected ${session.size}, got ${offset}`);
+            }
+            if (session.size + chunk.length > session.maxSize) {
+                throw new Error(`upload budget exceeded for ${uploadId}: max ${session.maxSize} bytes`);
+            }
+            const current = await staging.read(uploadId);
+            const next = new Uint8Array(current.length + chunk.length);
+            next.set(current, 0);
+            next.set(chunk, current.length);
+            await staging.write(uploadId, next);
+            session.size = next.length;
+            return { size: session.size };
+        },
+        async commit(uploadId, expected) {
+            const session = sessions.get(uploadId);
+            if (session === undefined)
+                throw new Error(`unknown upload: ${uploadId}`);
+            if (session.committed)
+                throw new Error(`upload already committed: ${uploadId}`);
+            const bytes = await staging.read(uploadId);
+            if (bytes.length !== expected.size) {
+                throw new Error(`upload size mismatch for ${uploadId}: staged ${bytes.length}, declared ${expected.size}`);
+            }
+            const actual = `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+            if (actual !== expected.digest) {
+                throw new Error(`upload digest mismatch for ${uploadId}: staged ${actual}`);
+            }
+            session.committed = true;
+            return { digest: actual, size: bytes.length };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,164 @@
 {
   "name": "@sentropic/artifacts",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Generic configurable artifacts MCP and artifact service: StorageScope/Artifact/Binding/Release model, canonical manifests, object authorization, idempotent intents (spec-v8 §9). Single 0.1.0 candidate for L-5a–5e; unpublished.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rhanka/sentropic.git",
+    "directory": "packages/artifacts"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./codecs": {
+      "types": "./dist/codecs.d.ts",
+      "import": "./dist/codecs.js"
+    },
+    "./server/ports": {
+      "types": "./dist/server/ports.d.ts",
+      "import": "./dist/server/ports.js"
+    },
+    "./server/service": {
+      "types": "./dist/server/service.d.ts",
+      "import": "./dist/server/service.js"
+    },
+    "./server/authorization": {
+      "types": "./dist/server/authorization.d.ts",
+      "import": "./dist/server/authorization.js"
+    },
+    "./server/bindings": {
+      "types": "./dist/server/bindings.d.ts",
+      "import": "./dist/server/bindings.js"
+    },
+    "./server/idempotency": {
+      "types": "./dist/server/idempotency.d.ts",
+      "import": "./dist/server/idempotency.js"
+    },
+    "./server/object-intents": {
+      "types": "./dist/server/object-intents.d.ts",
+      "import": "./dist/server/object-intents.js"
+    },
+    "./server/uploads": {
+      "types": "./dist/server/uploads.d.ts",
+      "import": "./dist/server/uploads.js"
+    },
+    "./server/publication": {
+      "types": "./dist/server/publication.d.ts",
+      "import": "./dist/server/publication.js"
+    },
+    "./server/access": {
+      "types": "./dist/server/access.d.ts",
+      "import": "./dist/server/access.js"
+    },
+    "./server/sources": {
+      "types": "./dist/server/sources.d.ts",
+      "import": "./dist/server/sources.js"
+    },
+    "./server/fork": {
+      "types": "./dist/server/fork.d.ts",
+      "import": "./dist/server/fork.js"
+    },
+    "./server/lifecycle": {
+      "types": "./dist/server/lifecycle.d.ts",
+      "import": "./dist/server/lifecycle.js"
+    },
+    "./server/gc": {
+      "types": "./dist/server/gc.d.ts",
+      "import": "./dist/server/gc.js"
+    },
+    "./server/runtime": {
+      "types": "./dist/server/runtime.d.ts",
+      "import": "./dist/server/runtime.js"
+    },
+    "./server/reader-profile": {
+      "types": "./dist/server/reader-profile.d.ts",
+      "import": "./dist/server/reader-profile.js"
+    },
+    "./server/templates": {
+      "types": "./dist/server/templates.d.ts",
+      "import": "./dist/server/templates.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
+    },
+    "./content/grants": {
+      "types": "./dist/content/grants.d.ts",
+      "import": "./dist/content/grants.js"
+    },
+    "./content/handler": {
+      "types": "./dist/content/handler.d.ts",
+      "import": "./dist/content/handler.js"
+    },
+    "./content/routing": {
+      "types": "./dist/content/routing.d.ts",
+      "import": "./dist/content/routing.js"
+    },
+    "./content/headers": {
+      "types": "./dist/content/headers.d.ts",
+      "import": "./dist/content/headers.js"
+    },
+    "./content/api-profile": {
+      "types": "./dist/content/api-profile.d.ts",
+      "import": "./dist/content/api-profile.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "import": "./dist/http.js"
+    },
+    "./parameters": {
+      "types": "./dist/parameters.d.ts",
+      "import": "./dist/parameters.js"
+    },
+    "./provider": {
+      "types": "./dist/provider-definition.d.ts",
+      "import": "./dist/provider-definition.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "provenance": true,
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run tests"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.980.0",
+    "pg": "^8.12.0"
+  },
+  "peerDependencies": {
+    "@sentropic/mcp-platform": ">=0.3.0 <0.4.0"
+  },
+  "peerDependenciesMeta": {
+    "@sentropic/mcp-platform": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.10",
+    "@types/pg": "^8.15.5",
+    "typescript": "5.4.5",
+    "vitest": "4.1.0"
+  }
+}