@sequenceholdings/artifact-studio 0.1.5 → 0.1.9

package/dist/git-service-client.js

@@ -0,0 +1,122 @@
+import { lstat, mkdir, realpath, unlink, writeFile } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { getJson, getJsonOr404 } from './api.js';
+const REPO_PAGE_SIZE = 200;
+/**
+ * Encode a `/`-delimited git path for a `[...path]` / `[...ref]` catch-all
+ * route: keep `/` as segment separators, percent-encode each segment so a
+ * branch like `feature/x` or a path with spaces survives the URL.
+ */
+function encodeSegments(path) {
+    return path
+        .split('/')
+        .map((segment) => encodeURIComponent(segment))
+        .join('/');
+}
+/** Resolve `namespace/name` to a repo id + default branch (FGA-filtered list, paginated). */
+export async function resolveRepo({ baseUrl, token, namespace, name, }) {
+    const ns = await getJsonOr404({
+        baseUrl,
+        token,
+        path: `/api/git-service/namespaces/${encodeURIComponent(namespace)}`,
+    });
+    if (!ns)
+        throw new Error(`Git-service namespace "${namespace}" not found on ${baseUrl}.`);
+    for (let offset = 0;; offset += REPO_PAGE_SIZE) {
+        const page = await getJson({
+            baseUrl,
+            token,
+            path: `/api/git-service/repos?namespaceId=${encodeURIComponent(ns.id)}&limit=${REPO_PAGE_SIZE}&offset=${offset}`,
+        });
+        const match = page.items.find((repo) => repo.name === name);
+        if (match)
+            return { id: match.id, defaultBranch: match.defaultBranch };
+        // Stop when this page was the last one (or empty) — the list endpoint is
+        // FGA-filtered, so total counts only repos the caller can read.
+        if (page.items.length === 0 || offset + page.items.length >= page.total)
+            break;
+    }
+    throw new Error(`Repo "${namespace}/${name}" not found (or not readable) on ${baseUrl}.`);
+}
+/**
+ * Resolve a ref (branch, tag, short name, or 40-hex SHA) to its commit SHA.
+ * Tries the refs endpoint first (cheap), then commit detail (which also
+ * verifies a raw SHA points at a real commit).
+ */
+export async function resolveCommitSha({ baseUrl, token, repoId, ref, }) {
+    const fromRef = await getJsonOr404({
+        baseUrl,
+        token,
+        path: `/api/git-service/repos/${repoId}/refs/${encodeSegments(ref)}`,
+    });
+    if (fromRef)
+        return fromRef.sha;
+    const fromCommit = await getJsonOr404({
+        baseUrl,
+        token,
+        path: `/api/git-service/repos/${repoId}/commits/${encodeSegments(ref)}`,
+    });
+    if (fromCommit)
+        return fromCommit.sha;
+    throw new Error(`Ref "${ref}" not found in repo ${repoId}.`);
+}
+/**
+ * Materialize the full tree at `ref` into `destDir` (recursive tree listing +
+ * one content fetch per blob). Returns the number of files written.
+ */
+export async function materializeRepo({ baseUrl, token, repoId, ref, destDir, }) {
+    const tree = await getJson({
+        baseUrl,
+        token,
+        path: `/api/git-service/repos/${repoId}/tree?recursive=true&ref=${encodeURIComponent(ref)}`,
+    });
+    const blobs = tree.entries.filter((entry) => entry.type === 'blob');
+    const root = resolve(destDir);
+    // The destination itself must not be a pre-existing symlink — mkdir and
+    // realpath would follow it, every containment check below would pass
+    // relative to the link TARGET, and the whole tree would land outside the
+    // requested path.
+    const rootStat = await lstat(root).catch(() => null);
+    if (rootStat?.isSymbolicLink()) {
+        throw new Error(`Refusing to materialize into a symlinked destination: ${destDir}`);
+    }
+    const rootPrefix = root + sep;
+    await mkdir(root, { recursive: true });
+    // Symlink defense root: writeFile FOLLOWS symlinks, so the lexical check
+    // below doesn't stop a pre-existing symlink inside destDir (e.g. a pnpm
+    // node_modules tree pulled into with `repos pull --force`) from routing a
+    // write outside it. Each file's parent must realpath-resolve back inside
+    // the destination, and the file itself must not be a symlink.
+    const rootReal = await realpath(root);
+    const rootRealPrefix = rootReal + sep;
+    for (const blob of blobs) {
+        const dest = resolve(destDir, blob.path);
+        // Defense in depth: the service rejects `..` paths on write, but never let a
+        // crafted tree escape the destination directory on the way out.
+        if (dest !== root && !dest.startsWith(rootPrefix)) {
+            throw new Error(`Refusing to write outside destination: ${blob.path}`);
+        }
+        const file = await getJson({
+            baseUrl,
+            token,
+            path: `/api/git-service/repos/${repoId}/contents/${encodeSegments(blob.path)}?ref=${encodeURIComponent(ref)}`,
+        });
+        await mkdir(dirname(dest), { recursive: true });
+        const parentReal = await realpath(dirname(dest));
+        if (parentReal !== rootReal && !parentReal.startsWith(rootRealPrefix)) {
+            throw new Error(`Refusing to write through symlinked directory: ${blob.path}`);
+        }
+        const existing = await lstat(dest).catch(() => null);
+        if (existing?.isSymbolicLink()) {
+            throw new Error(`Refusing to write through symlink: ${blob.path}`);
+        }
+        // Replace rather than overwrite-in-place: unlinking first breaks any
+        // pre-existing hardlink (writeFile would otherwise update the shared
+        // inode — data reachable outside the destination) and closes the
+        // lstat→write window on the symlink check above.
+        if (existing)
+            await unlink(dest);
+        await writeFile(dest, Buffer.from(file.content, 'base64'));
+    }
+    return blobs.length;
+}

package/dist/hash.d.ts

@@ -4,6 +4,18 @@ export interface HashableArtifactFile {
     encoding?: string;
 }
 export declare function sha256Hex(content: string | Buffer): string;
+/**
+ * Hash of a deployable source tree. `manifest` MUST be the RAW yaml-loaded
+ * `artifact.bundle.yml` object, never the zod-parsed manifest: parsing fills
+ * schema defaults, so hashing the parsed object changes the digest of
+ * byte-identical sources every time the manifest schema gains a defaulted
+ * field — and a CLI built against an older schema then disagrees with the
+ * server forever (`artifact plan` reported perpetual drift after
+ * `capabilities.uses` landed). The raw object only changes when the file
+ * bytes change. Must stay byte-identical to the Atlas server hasher
+ * (atlas/src/server/services/artifact-studio/hash.ts) — pinned by
+ * hash-parity.test.ts.
+ */
 export declare function computeSourceHash({ files, manifest, }: {
     files: readonly HashableArtifactFile[];
     manifest: unknown;

package/dist/hash.js

@@ -14,9 +14,21 @@ function stableJson(value) {
         .map((key) => `${JSON.stringify(key)}:${stableJson(obj[key])}`)
         .join(',')}}`;
 }
+/**
+ * Hash of a deployable source tree. `manifest` MUST be the RAW yaml-loaded
+ * `artifact.bundle.yml` object, never the zod-parsed manifest: parsing fills
+ * schema defaults, so hashing the parsed object changes the digest of
+ * byte-identical sources every time the manifest schema gains a defaulted
+ * field — and a CLI built against an older schema then disagrees with the
+ * server forever (`artifact plan` reported perpetual drift after
+ * `capabilities.uses` landed). The raw object only changes when the file
+ * bytes change. Must stay byte-identical to the Atlas server hasher
+ * (atlas/src/server/services/artifact-studio/hash.ts) — pinned by
+ * hash-parity.test.ts.
+ */
 export function computeSourceHash({ files, manifest, }) {
     const h = createHash('sha256');
-    h.update('artifact-studio-source-v2\0');
+    h.update('artifact-studio-source-v3\0');
     h.update(stableJson(manifest));
     h.update('\0');
     const sorted = [...files].map((file) => ({

package/dist/lockfile-origin.d.ts

@@ -0,0 +1,6 @@
+/**
+ * CLI-side mirror of studio-cli/functions/lockfile-origin.ts and
+ * atlas/.../managed-functions/lockfile-origin.ts — keep the three in sync.
+ */
+export type LockfileOrigin = 'chainguard' | 'npm' | 'unknown';
+export declare function classifyLockfileOrigin(lockfileText: string): LockfileOrigin;

package/dist/lockfile-origin.js

@@ -0,0 +1,41 @@
+import { load as parseYaml } from 'js-yaml';
+const CHAINGUARD_TARBALL_HOST = 'libraries.cgr.dev';
+const NPM_TARBALL_HOST = 'registry.npmjs.org';
+export function classifyLockfileOrigin(lockfileText) {
+    let parsed;
+    try {
+        const doc = parseYaml(lockfileText);
+        if (!doc || typeof doc !== 'object')
+            return 'unknown';
+        parsed = doc;
+    }
+    catch {
+        return 'unknown';
+    }
+    const packages = parsed.packages;
+    if (!packages || typeof packages !== 'object')
+        return 'unknown';
+    let sawChainguard = false;
+    let sawNpm = false;
+    for (const entry of Object.values(packages)) {
+        const tarball = entry?.resolution?.tarball;
+        if (typeof tarball !== 'string')
+            continue;
+        let host;
+        try {
+            host = new URL(tarball).host.toLowerCase();
+        }
+        catch {
+            continue;
+        }
+        if (host === NPM_TARBALL_HOST)
+            sawNpm = true;
+        else if (host === CHAINGUARD_TARBALL_HOST)
+            sawChainguard = true;
+    }
+    if (sawNpm)
+        return 'npm';
+    if (sawChainguard)
+        return 'chainguard';
+    return 'unknown';
+}

package/dist/manifest-custom-roles.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Custom Roles & Capabilities (PER-61) — the `capabilities.roles` manifest
+ * block. Kept in its own module (imported by `manifest.ts`). CLI-side mirror of
+ * atlas/src/server/services/artifact-studio/manifest-custom-roles.ts — same
+ * pattern as the duplicated manifest schema. Keep the two copies in sync.
+ */
+import { z } from 'zod';
+/**
+ * Key grammar for roles and capabilities. Deliberately excludes `_` so the
+ * FGA object id `custom_role:artifact_<projectId>__<key>` can use `__` as an
+ * unambiguous delimiter.
+ */
+export declare const CUSTOM_ROLE_KEY_RE: RegExp;
+/**
+ * Manifest-declared custom roles & capabilities. Roles and capabilities are
+ * both `custom_role` FGA objects; deploy reconciliation turns this block into
+ * the structural waterfall edges (role→capability / senior→junior `assignee`
+ * userset tuples) — nothing else. The host floor is enforced app-layer at the
+ * resolution points, never in the model. Runtime grants (user/group/org →
+ * role) are NEVER declared here — they are written through host-admin-gated
+ * endpoints.
+ */
+export declare const customRolesBlockSchema: z.ZodObject<{
+    definitions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodDefault<z.ZodBoolean>;
+        inherits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    capabilities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ArtifactStudioCustomRoles = z.infer<typeof customRolesBlockSchema>;
+/** True when the block declares at least one role or capability. */
+export declare function customRolesDeclared(block: ArtifactStudioCustomRoles | null | undefined): boolean;
+/**
+ * Capability pins (PER-76) — the `capabilities.uses` attachment set. A pin
+ * references a REGISTRY capability the host's code checks: `org/<key>` for
+ * an org-scoped capability (must already exist — hosts never create org
+ * entities), or a bare `<key>` for a project-scoped one (declared in this
+ * manifest's `capabilities.roles.capabilities` record, or already published
+ * to the host's registry scope). Roles are never pinned — composition and
+ * grants are live runtime configuration owned by the registry.
+ */
+export declare const CUSTOM_CAPABILITY_PIN_RE: RegExp;
+export declare const capabilityPinsSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
+export interface ParsedCapabilityPin {
+    scope: 'org' | 'project';
+    key: string;
+}
+/** Split a pin into its scope and key. Assumes the pin grammar validated. */
+export declare function parseCapabilityPin(pin: string): ParsedCapabilityPin;
+/**
+ * Cross-field pin validation, called from the manifest superRefine (the
+ * `uses` array and the roles block are siblings under `capabilities`).
+ * Purely structural — registry existence checks are server-side, at
+ * activation, where atomicity lives.
+ */
+export declare function validateCapabilityPins({ uses, roles, }: {
+    uses: readonly string[];
+    roles: ArtifactStudioCustomRoles | null | undefined;
+}): string[];

package/dist/manifest-custom-roles.js

@@ -0,0 +1,194 @@
+/**
+ * Custom Roles & Capabilities (PER-61) — the `capabilities.roles` manifest
+ * block. Kept in its own module (imported by `manifest.ts`). CLI-side mirror of
+ * atlas/src/server/services/artifact-studio/manifest-custom-roles.ts — same
+ * pattern as the duplicated manifest schema. Keep the two copies in sync.
+ */
+import { z } from 'zod';
+/**
+ * Key grammar for roles and capabilities. Deliberately excludes `_` so the
+ * FGA object id `custom_role:artifact_<projectId>__<key>` can use `__` as an
+ * unambiguous delimiter.
+ */
+export const CUSTOM_ROLE_KEY_RE = /^[a-z0-9-]+$/;
+const customRoleKeySchema = z.string().min(1).max(64).regex(CUSTOM_ROLE_KEY_RE, 'Role and capability keys must match [a-z0-9-]+');
+const MAX_CUSTOM_ROLE_DEFINITIONS = 50;
+const MAX_CUSTOM_ROLE_CAPABILITIES = 100;
+const customRoleCapabilityDeclarationSchema = z.object({
+    description: z.string().max(500).optional(),
+});
+const customRoleDefinitionSchema = z.object({
+    description: z.string().max(500).optional(),
+    /**
+     * Grants this role to the host's entire runtime audience. Resolved at the
+     * app layer at claim time — every caller who passes the host floor
+     * (`end_user`) holds the default roles; no tuple is written for it.
+     */
+    default: z.boolean().default(false),
+    /** Role keys whose grants this role also receives (privilege waterfall). */
+    inherits: z.array(customRoleKeySchema).default([]),
+    /** Capability keys this role grants directly. */
+    grants: z.array(customRoleKeySchema).default([]),
+});
+/**
+ * Manifest-declared custom roles & capabilities. Roles and capabilities are
+ * both `custom_role` FGA objects; deploy reconciliation turns this block into
+ * the structural waterfall edges (role→capability / senior→junior `assignee`
+ * userset tuples) — nothing else. The host floor is enforced app-layer at the
+ * resolution points, never in the model. Runtime grants (user/group/org →
+ * role) are NEVER declared here — they are written through host-admin-gated
+ * endpoints.
+ */
+export const customRolesBlockSchema = z.object({
+    /** Roles grantable to principals, keyed by role key. */
+    definitions: z.record(customRoleKeySchema, customRoleDefinitionSchema).default({}),
+    /** Leaf capability keys the artifact's code checks, keyed by capability key. */
+    capabilities: z.record(customRoleKeySchema, customRoleCapabilityDeclarationSchema).default({}),
+}).superRefine((block, ctx) => {
+    const roleKeys = Object.keys(block.definitions);
+    const capabilityKeys = new Set(Object.keys(block.capabilities));
+    if (roleKeys.length > MAX_CUSTOM_ROLE_DEFINITIONS) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `At most ${MAX_CUSTOM_ROLE_DEFINITIONS} role definitions are allowed`,
+            path: ['definitions'],
+        });
+    }
+    if (capabilityKeys.size > MAX_CUSTOM_ROLE_CAPABILITIES) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `At most ${MAX_CUSTOM_ROLE_CAPABILITIES} capabilities are allowed`,
+            path: ['capabilities'],
+        });
+    }
+    // Roles and capabilities share one FGA object namespace on the host —
+    // a key present in both would collapse two objects into one.
+    for (const key of roleKeys) {
+        if (capabilityKeys.has(key)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Key "${key}" is declared as both a role and a capability`,
+                path: ['definitions', key],
+            });
+        }
+    }
+    const roleKeySet = new Set(roleKeys);
+    for (const [roleKey, definition] of Object.entries(block.definitions)) {
+        const seenInherits = new Set();
+        for (const inherited of definition.inherits) {
+            if (seenInherits.has(inherited)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" lists "${inherited}" in inherits more than once`,
+                    path: ['definitions', roleKey, 'inherits'],
+                });
+            }
+            seenInherits.add(inherited);
+            if (!roleKeySet.has(inherited)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" inherits unknown role "${inherited}"`,
+                    path: ['definitions', roleKey, 'inherits'],
+                });
+            }
+        }
+        const seenGrants = new Set();
+        for (const granted of definition.grants) {
+            if (seenGrants.has(granted)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" lists "${granted}" in grants more than once`,
+                    path: ['definitions', roleKey, 'grants'],
+                });
+            }
+            seenGrants.add(granted);
+            if (!capabilityKeys.has(granted)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Role "${roleKey}" grants unknown capability "${granted}"`,
+                    path: ['definitions', roleKey, 'grants'],
+                });
+            }
+        }
+    }
+    // The inherits graph must be a DAG: a cycle would make the FGA waterfall
+    // walk self-referential. DFS with tri-color marking; report the first
+    // cycle found.
+    const state = new Map();
+    const visit = (key, path) => {
+        if (state.get(key) === 'done')
+            return null;
+        if (state.get(key) === 'visiting')
+            return [...path, key];
+        state.set(key, 'visiting');
+        const definition = block.definitions[key];
+        for (const inherited of definition?.inherits ?? []) {
+            if (!roleKeySet.has(inherited))
+                continue;
+            const cycle = visit(inherited, [...path, key]);
+            if (cycle)
+                return cycle;
+        }
+        state.set(key, 'done');
+        return null;
+    };
+    for (const roleKey of roleKeys) {
+        const cycle = visit(roleKey, []);
+        if (cycle) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Role inheritance cycle: ${cycle.join(' -> ')}`,
+                path: ['definitions'],
+            });
+            break;
+        }
+    }
+});
+/** True when the block declares at least one role or capability. */
+export function customRolesDeclared(block) {
+    if (!block)
+        return false;
+    return Object.keys(block.definitions).length > 0 || Object.keys(block.capabilities).length > 0;
+}
+/**
+ * Capability pins (PER-76) — the `capabilities.uses` attachment set. A pin
+ * references a REGISTRY capability the host's code checks: `org/<key>` for
+ * an org-scoped capability (must already exist — hosts never create org
+ * entities), or a bare `<key>` for a project-scoped one (declared in this
+ * manifest's `capabilities.roles.capabilities` record, or already published
+ * to the host's registry scope). Roles are never pinned — composition and
+ * grants are live runtime configuration owned by the registry.
+ */
+export const CUSTOM_CAPABILITY_PIN_RE = /^(?:org\/)?[a-z0-9-]+$/;
+const MAX_CAPABILITY_PINS = 100;
+export const capabilityPinsSchema = z
+    .array(z.string().min(1).max(68).regex(CUSTOM_CAPABILITY_PIN_RE, 'Pins must be "org/<key>" or a bare "<key>" matching [a-z0-9-]+'))
+    .max(MAX_CAPABILITY_PINS)
+    .default([]);
+/** Split a pin into its scope and key. Assumes the pin grammar validated. */
+export function parseCapabilityPin(pin) {
+    return pin.startsWith('org/')
+        ? { scope: 'org', key: pin.slice('org/'.length) }
+        : { scope: 'project', key: pin };
+}
+/**
+ * Cross-field pin validation, called from the manifest superRefine (the
+ * `uses` array and the roles block are siblings under `capabilities`).
+ * Purely structural — registry existence checks are server-side, at
+ * activation, where atomicity lives.
+ */
+export function validateCapabilityPins({ uses, roles, }) {
+    const errors = [];
+    const seen = new Set();
+    const roleKeys = new Set(Object.keys(roles?.definitions ?? {}));
+    for (const pin of uses) {
+        if (seen.has(pin))
+            errors.push(`Pin "${pin}" is listed more than once`);
+        seen.add(pin);
+        const parsed = parseCapabilityPin(pin);
+        if (parsed.scope === 'project' && roleKeys.has(parsed.key)) {
+            errors.push(`Pin "${pin}" references a role — roles are never pinned`);
+        }
+    }
+    return errors;
+}

package/dist/manifest.d.ts

@@ -1,4 +1,14 @@
 import { z } from 'zod';
+export { CUSTOM_CAPABILITY_PIN_RE, CUSTOM_ROLE_KEY_RE, capabilityPinsSchema, customRolesBlockSchema, customRolesDeclared, parseCapabilityPin, validateCapabilityPins, type ArtifactStudioCustomRoles, type ParsedCapabilityPin, } from './manifest-custom-roles.js';
+export declare const sidebarBadgeSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        alert: "alert";
+        muted: "muted";
+    }>>;
+}, z.core.$strip>;
+export type SidebarBadgeManifest = z.infer<typeof sidebarBadgeSchema>;
+export declare function apiCapabilityPathAllowed(pathname: string, allowed: readonly string[]): boolean;
 export declare const artifactStudioManifestSchema: z.ZodObject<{
     bundle: z.ZodObject<{
         name: z.ZodString;
@@ -30,6 +40,20 @@ export declare const artifactStudioManifestSchema: z.ZodObject<{
         functions: z.ZodDefault<z.ZodObject<{
             invoke: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        allow_downloads: z.ZodDefault<z.ZodBoolean>;
+        allow_popups: z.ZodDefault<z.ZodBoolean>;
+        roles: z.ZodOptional<z.ZodObject<{
+            definitions: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+                default: z.ZodDefault<z.ZodBoolean>;
+                inherits: z.ZodDefault<z.ZodArray<z.ZodString>>;
+                grants: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            capabilities: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+                description: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        uses: z.ZodDefault<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     targets: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         url: z.ZodString;
@@ -39,6 +63,13 @@ export declare const artifactStudioManifestSchema: z.ZodObject<{
             published: "published";
         }>>;
     }, z.core.$strip>>>;
+    sidebarBadge: z.ZodOptional<z.ZodObject<{
+        endpoint: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            alert: "alert";
+            muted: "muted";
+        }>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type ArtifactStudioManifest = z.infer<typeof artifactStudioManifestSchema>;
 export declare function parseArtifactStudioManifest(value: unknown): ArtifactStudioManifest;

package/dist/manifest.js

@@ -1,10 +1,44 @@
 import { z } from 'zod';
+import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins, } from './manifest-custom-roles.js';
 import { normalizeArtifactPath } from './paths.js';
+export { CUSTOM_CAPABILITY_PIN_RE, CUSTOM_ROLE_KEY_RE, capabilityPinsSchema, customRolesBlockSchema, customRolesDeclared, parseCapabilityPin, validateCapabilityPins, } from './manifest-custom-roles.js';
 const apiCapabilityPathSchema = z.string().min(1).refine((path) => path.startsWith('/api/') && path !== '/api/' && path !== '/api/*', 'API capability paths must be scoped below /api/');
 const apiCapabilitiesSchema = z.object({
     read: z.array(apiCapabilityPathSchema).default([]),
     write: z.array(apiCapabilityPathSchema).default([]),
 }).default({ read: [], write: [] });
+const sidebarBadgeToneSchema = z.enum(['alert', 'muted']);
+export const sidebarBadgeSchema = z.object({
+    endpoint: apiCapabilityPathSchema,
+    tone: sidebarBadgeToneSchema.optional(),
+});
+function matchesApiCapabilityEntry(pathname, entry) {
+    if (!entry.startsWith('/api/'))
+        return false;
+    if (entry === pathname)
+        return true;
+    if (entry.includes('*') && (!entry.endsWith('/*') || hasMidPathWildcard(entry))) {
+        const pathParts = pathname.split('/');
+        const entryParts = entry.split('/');
+        return (pathParts.length === entryParts.length &&
+            entryParts.every((part, index) => part === '*' || part === pathParts[index]));
+    }
+    if (entry.endsWith('/*')) {
+        const prefix = entry.slice(0, -1);
+        return pathname.startsWith(prefix);
+    }
+    if (entry.endsWith('/')) {
+        return pathname.startsWith(entry);
+    }
+    return false;
+}
+function hasMidPathWildcard(entry) {
+    const parts = entry.split('/');
+    return parts.slice(1, -1).some((part) => part === '*');
+}
+export function apiCapabilityPathAllowed(pathname, allowed) {
+    return allowed.some((entry) => matchesApiCapabilityEntry(pathname, entry));
+}
 export const artifactStudioManifestSchema = z.object({
     bundle: z.object({
         name: z.string().min(1).max(255),
@@ -30,15 +64,58 @@ export const artifactStudioManifestSchema = z.object({
         functions: z.object({
             invoke: z.array(z.string().min(1)).default([]),
         }).default({ invoke: [] }),
+        /** Opt-in: enables iframe `allow-downloads`. Default false. */
+        allow_downloads: z.boolean().default(false),
+        /**
+         * Opt-in: enables iframe `allow-popups allow-popups-to-escape-sandbox` so
+         * the artifact can open a new top-level (unsandboxed) browser tab — needed
+         * to render a PDF in the native viewer, which the sandbox CSP blocks
+         * in-frame. Default false; grant only to trusted-authored artifacts.
+         */
+        allow_popups: z.boolean().default(false),
+        /**
+         * Custom Roles & Capabilities (PER-61): manifest-declared roles and the
+         * capability keys the artifact's code checks. Reconciled into
+         * `custom_role` FGA structural tuples when a deploy activates.
+         */
+        roles: customRolesBlockSchema.optional(),
+        /**
+         * Capability pins (PER-76): registry capabilities this artifact's code
+         * checks — `org/<key>` or a bare project-scoped `<key>`. Reconciled into
+         * the host's attachment set at activation; existence is validated
+         * server-side there.
+         */
+        uses: capabilityPinsSchema,
     }).default({
         data: { read: [], write: [] },
         api: { read: [], write: [] },
         functions: { invoke: [] },
+        allow_downloads: false,
+        allow_popups: false,
+        uses: [],
     }),
     targets: z.record(z.string().min(1), z.object({
         url: z.string().url(),
         visibility: z.enum(['private', 'shared', 'published']).default('private'),
     })).default({}),
+    sidebarBadge: sidebarBadgeSchema.optional(),
+}).superRefine((manifest, ctx) => {
+    for (const message of validateCapabilityPins({
+        uses: manifest.capabilities.uses,
+        roles: manifest.capabilities.roles,
+    })) {
+        ctx.addIssue({ code: 'custom', message, path: ['capabilities', 'uses'] });
+    }
+    if (!manifest.sidebarBadge)
+        return;
+    const endpoint = manifest.sidebarBadge.endpoint;
+    if (!apiCapabilityPathAllowed(endpoint, manifest.capabilities.api.read)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `sidebarBadge.endpoint ${endpoint} must be declared in capabilities.api.read`,
+            path: ['sidebarBadge', 'endpoint'],
+        });
+    }
 });
 export function parseArtifactStudioManifest(value) {
     return artifactStudioManifestSchema.parse(value);

package/dist/prepare-build.d.ts

@@ -0,0 +1,21 @@
+/** Chainguard registry routing for ephemeral remote builds. */
+export declare const ARTIFACT_BUILD_NPMRC = "; Ephemeral install config for seq-studio artifact builds.\nregistry=https://libraries.cgr.dev/javascript/\n//libraries.cgr.dev/javascript/:always-auth=true\n//libraries.cgr.dev/javascript-upstream/:always-auth=true\nignore-scripts=true\nmanage-package-manager-versions=false\n";
+/** Pull only Chainguard registry auth lines from the developer ~/.npmrc. */
+export declare function extractChainguardAuthLines(userNpmrc: string): string[];
+/** Merge trusted Chainguard auth from ~/.npmrc with pinned install settings. */
+export declare function buildControlledArtifactNpmrc(userNpmrcPath?: string): string;
+export interface PrepareBuildOptions {
+    /** Remote sources (--repo / --git-url) install when package.json exists. */
+    remote?: boolean;
+}
+/**
+ * Whether the build should run `pnpm install` before Vite bundles the tree.
+ * Only remote materializations (--repo / --git-url) are bare and need install.
+ */
+export declare function shouldInstallArtifactDependencies(dir: string, opts?: PrepareBuildOptions): boolean;
+/**
+ * Install artifact runtime deps into the build root. Platform peers (react,
+ * atlas-ui, react-query, artifact-studio SDK) are still force-aliased at build
+ * time — this step resolves app-specific imports like recharts or reactflow.
+ */
+export declare function prepareArtifactBuildRoot(dir: string, opts?: PrepareBuildOptions): Promise<void>;