@sequenceholdings/artifact-studio 0.3.1 → 0.4.0

package/README.md

@@ -3,6 +3,43 @@
 `@sequenceholdings/artifact-studio` exposes the host-provided `seq` client. Runtime
 requests use the current user's normal permissions.
 
+## Governed ORM operations
+
+Use the published caller-aware adapter inside an Artifact Studio Preview or a
+deployed artifact. Generate and apply the namespace first, then import its
+`operations.manifest.json` into your application:
+
+```ts
+import { createArtifactOrmExecutor } from '@sequenceholdings/artifact-studio'
+import manifest from './operations.manifest.json'
+
+const orm = createArtifactOrmExecutor({ namespace: 'team_directory', manifest })
+const result = await orm.execute('Profiles', { limit: 100, offset: 0 })
+```
+
+Declare the exact namespace path in `artifact.bundle.yml`:
+
+```yaml
+capabilities:
+  api:
+    write: ['/api/data/v2/team_directory']
+```
+
+Persisted queries and mutations both use POST, so both require this `write`
+declaration. This declaration permits the artifact to make the request; each
+user still needs namespace runtime access and the operation's role/capability.
+ORM row policies and write checks enforce that caller's access. The helper uses
+host authentication and requires no token, custom header, or environment URL.
+The namespace path above is a capability declaration, not a direct HTTP API
+contract for external clients.
+
+The adapter validates the namespace and manifest, rejects unknown operations,
+and returns the operation's `data`. Errors retain `OrmOperationError.status`,
+`code`, and `errors`; missing host context or malformed success responses fail
+instead of reporting saved data. Calls are never automatically retried. For
+several operations in one traced UI action, pass `withTraceAction`'s client as
+the optional `sdk` argument.
+
 Artifact Studio is a workflow-agnostic platform primitive. The host, SDK, and
 deployer provide generic application capabilities; each deployed artifact owns
 its product behavior. Primitive code must not branch on an artifact ID or import

package/dist/build.js

@@ -78,6 +78,7 @@ function createPeerResolveAlias({ atlasUiPackageDir = atlasUiDir } = {}) {
         'react-router-dom': reactRouterDomDir,
         sonner: sonnerDir,
         '@sequenceholdings/storage': cliRequire.resolve('@sequenceholdings/storage'),
+        '@sequenceholdings/orm/client': cliRequire.resolve('@sequenceholdings/orm/client'),
         // Candidate Atlas UI exposes canonical tokens at the package root; released
         // 2.0.1 keeps them in dist. Preserve explicit alias resolution so legacy
         // source reaches the normalizer instead of falling through to the bare alias.

package/dist/cli.js

@@ -18,6 +18,7 @@ import { lintArtifactSandbox, reportSandboxWarnings } from './sandbox-lint.js';
 import { assertActiveDeployProvenance } from './active-deploy-policy.js';
 import { normalizeArtifactPath } from './paths.js';
 import yaml from 'js-yaml';
+import { warnOnRoleDefinitions } from './role-definitions-notice.js';
 const COMMANDS = [
     'init', 'whoami', 'link', 'env', 'status', 'list', 'show',
     'validate', 'build', 'plan', 'deploy', 'dev', 'promote', 'pull', 'rollback',
@@ -505,7 +506,10 @@ async function deployCommand(args) {
         // the current branch and dirty working tree.
         if (env.name !== 'local')
             assertActiveDeployProvenance(source.provenance);
-        if (isNextArtifactManifest(await readArtifactStudioManifest(source.dir))) {
+        const manifest = await readArtifactStudioManifest(source.dir);
+        // After source resolution, so --repo / --git-url deploys check the fetched manifest.
+        warnOnRoleDefinitions(manifest);
+        if (isNextArtifactManifest(manifest)) {
             return await buildNextCommand({ args, source, active: true });
         }
         // --skip-unchanged: hash the raw source (no build needed) and no-op when

package/dist/dev-link.js

@@ -8,7 +8,7 @@ import { dirname, join, relative, resolve } from 'node:path';
 export function hasLinkedAtlasUiToolchain({ deps }) {
     return deps.some((dep) => dep.name === '@sequenceholdings/atlas-ui');
 }
-const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.json']);
+const WATCHED_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.json']);
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.turbo', '.cache']);
 const defaultResolver = createRequire(import.meta.url).resolve;
 /** Split a `--link a,b` flag value into trimmed, non-empty paths. */

package/dist/gateway/server.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type TunnelLease, type TunnelBrokerOptions } from '../tunnel/index.js';
 import { ArtifactGatewayControl } from './control.js';
+import { type GatewaySessionSameSite } from './session.js';
 import { type ArtifactRequestAdmission } from './admission.js';
 import { type GatewayControlAdmission } from './control-admission.js';
 export interface ArtifactGatewayOptions {
@@ -9,6 +10,8 @@ export interface ArtifactGatewayOptions {
     parentOrigin: string;
     gatewayOrigin: string;
     sessionKey: string;
+    /** Defaults to `Strict`. `None` only for a local development gateway (see GatewaySessionSameSite). */
+    sessionCookieSameSite?: GatewaySessionSameSite;
     contextPrivateKey: string;
     contextKeyId: string;
     /** Unique per process, never a shared Cloud Run revision name. */

package/dist/gateway/server.js

@@ -136,7 +136,7 @@ export function createArtifactGateway(options) {
         }
         if (session.publicOrigin !== origin || session.bridge.parentOrigin !== parentOrigin)
             throw new GatewayControlError(403);
-        response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie') }));
+        response.setHeader('set-cookie', gatewaySessionCookies({ session, key: options.sessionKey, cookie: header(request, 'cookie'), sameSite: options.sessionCookieSameSite }));
         json(response, 200, 'connected');
     }
     /** Tunnel credential validation, shared by connection admission and every lease check. */
@@ -319,7 +319,7 @@ export function createArtifactGateway(options) {
             }
             const renewed = renewGatewaySession({ session, authorizedExpiresAt: target.expiresAt });
             if (renewed)
-                response.setHeader('set-cookie', gatewaySessionCookies({ session: renewed, key: options.sessionKey, cookie: header(request, 'cookie'), renewal: true }));
+                response.setHeader('set-cookie', gatewaySessionCookies({ session: renewed, key: options.sessionKey, cookie: header(request, 'cookie'), renewal: true, sameSite: options.sessionCookieSameSite }));
             // Authorization precedes every response, including Next static assets and cached pages.
             response.setHeader('content-security-policy', `frame-ancestors ${session.bridge.parentOrigin}`);
             response.setHeader('referrer-policy', 'same-origin');

package/dist/gateway/session.d.ts

@@ -37,12 +37,25 @@ export declare function renewGatewaySession({ session, authorizedExpiresAt, now
     authorizedExpiresAt: number;
     now?: number;
 }): GatewaySession | null;
-export declare function gatewaySessionCookies({ session, key, cookie, renewal, now }: {
+/**
+ * `Strict` everywhere Atlas and the runtime domain are one site, as every deployed environment is.
+ * `None` is for the local stack only: Atlas on http://localhost is cross-site to
+ * https://*.apps.localhost, so browsers drop a `Strict` cookie inside the preview iframe.
+ * Partitioned keeps the relaxed cookie to Atlas's top-level site.
+ */
+export type GatewaySessionSameSite = 'Strict' | 'None';
+/** Reads ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE; only a development gateway may relax the cookie. */
+export declare function gatewaySessionSameSite({ value, appEnv }: {
+    value: string | undefined;
+    appEnv: string;
+}): GatewaySessionSameSite;
+export declare function gatewaySessionCookies({ session, key, cookie, renewal, now, sameSite }: {
     session: GatewaySession;
     key: string;
     cookie?: string;
     renewal?: boolean;
     now?: number;
+    sameSite?: GatewaySessionSameSite;
 }): string[];
 export declare function encodeGatewaySession({ session, key }: {
     session: GatewaySession;

package/dist/gateway/session.js

@@ -39,9 +39,23 @@ export function renewGatewaySession({ session, authorizedExpiresAt, now = Date.n
     const expiresAt = Math.min(authorizedExpiresAt, session.maxExpiresAt ?? session.expiresAt);
     return expiresAt > session.expiresAt ? { ...session, expiresAt } : null;
 }
-export function gatewaySessionCookies({ session, key, cookie, renewal = false, now = Date.now() }) {
+/** Reads ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE; only a development gateway may relax the cookie. */
+export function gatewaySessionSameSite({ value, appEnv }) {
+    if (value === undefined || value === '' || value === 'strict')
+        return 'Strict';
+    if (value !== 'none')
+        throw new Error('ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE must be "strict" or "none"');
+    if (appEnv !== 'development')
+        throw new Error('ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE=none is only for a local development gateway');
+    return 'None';
+}
+function cookieAttributes(sameSite) {
+    return `Path=/; HttpOnly; Secure; ${sameSite === 'None' ? 'SameSite=None; Partitioned' : 'SameSite=Strict'}`;
+}
+export function gatewaySessionCookies({ session, key, cookie, renewal = false, now = Date.now(), sameSite = 'Strict' }) {
     const maxAge = Math.max(0, Math.floor((session.expiresAt - now) / 1000));
-    const value = `${encodeGatewaySession({ session, key })}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${maxAge}`;
+    const attributes = cookieAttributes(sameSite);
+    const value = `${encodeGatewaySession({ session, key })}; ${attributes}; Max-Age=${maxAge}`;
     const current = renewal ? decodeGatewaySession({ cookie, key, origin: session.publicOrigin, now }) : session;
     if (!current || !sameSessionScope(current, session))
         return [];
@@ -63,7 +77,7 @@ export function gatewaySessionCookies({ session, key, cookie, renewal = false, n
                 revoked.push(name);
         }
         for (const name of [...revoked, ...sameScope.slice(0, Math.max(0, sameScope.length - 5))]) {
-            cookies.push(`${name}=; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=0`);
+            cookies.push(`${name}=; ${attributes}; Max-Age=0`);
         }
     }
     return cookies;

package/dist/gateway-main.js

@@ -3,6 +3,7 @@ import { isIP } from 'node:net';
 import { Redis } from 'ioredis';
 import { ArtifactGatewayControl } from './gateway/control.js';
 import { createArtifactGateway } from './gateway/server.js';
+import { gatewaySessionSameSite } from './gateway/session.js';
 import { RedisTunnelOwnership, RedisTunnelRelay } from './tunnel/redis.js';
 import { ArtifactRequestAdmission } from './gateway/admission.js';
 import { GatewayControlAdmission } from './gateway/control-admission.js';
@@ -61,6 +62,7 @@ async function main() {
         parentOrigin: process.env.ARTIFACT_NEXT_PARENT_ORIGIN ?? new URL(controlUrl).origin,
         gatewayOrigin: required('ARTIFACT_NEXT_GATEWAY_URL'),
         sessionKey,
+        sessionCookieSameSite: gatewaySessionSameSite({ value: process.env.ARTIFACT_NEXT_SESSION_COOKIE_SAMESITE, appEnv: namespace }),
         contextPrivateKey: required('ARTIFACT_NEXT_CONTEXT_PRIVATE_KEY'),
         contextKeyId: required('ARTIFACT_NEXT_CONTEXT_KEY_ID'),
         nodeId, routing: ownership, relay,

package/dist/loopback.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Hosts a browser always resolves to this machine: the loopback literals, `localhost` and every
+ * `*.localhost` name (RFC 6761). Browsers treat plain HTTP on them as a secure context, which is
+ * what lets local development serve application origins without TLS.
+ */
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** `local` and the per-worktree `local:<name>` environments seq-studio discovers. */
+export declare function isLocalEnvironmentName(name: string): boolean;

package/dist/loopback.js

@@ -0,0 +1,13 @@
+/**
+ * Hosts a browser always resolves to this machine: the loopback literals, `localhost` and every
+ * `*.localhost` name (RFC 6761). Browsers treat plain HTTP on them as a secure context, which is
+ * what lets local development serve application origins without TLS.
+ */
+export function isLoopbackHostname(hostname) {
+    const host = hostname.toLowerCase();
+    return host === '127.0.0.1' || host === '[::1]' || host === 'localhost' || host.endsWith('.localhost');
+}
+/** `local` and the per-worktree `local:<name>` environments seq-studio discovers. */
+export function isLocalEnvironmentName(name) {
+    return name === 'local' || name.startsWith('local:');
+}

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

@@ -42,13 +42,23 @@ export declare function customRolesDeclared(block: ArtifactStudioCustomRoles | n
  * 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.
+ *
+ * `app/<application-id>/<key>` pins a capability an Application defines in
+ * `sequence.app.yml`. It needn't exist yet (members deploy first) and counts
+ * only while the host is a member of that Application.
  */
 export declare const CUSTOM_CAPABILITY_PIN_RE: RegExp;
 export declare const capabilityPinsSchema: z.ZodDefault<z.ZodArray<z.ZodString>>;
-export interface ParsedCapabilityPin {
+export type ParsedCapabilityPin = {
     scope: 'org' | 'project';
     key: string;
 }
+/** An Application capability: live only while the project is a member of `applicationId`. */
+ | {
+    scope: 'app';
+    applicationId: string;
+    key: string;
+};
 /** Split a pin into its scope and key. Assumes the pin grammar validated. */
 export declare function parseCapabilityPin(pin: string): ParsedCapabilityPin;
 /**

package/dist/manifest-custom-roles.js

@@ -158,18 +158,26 @@ export function customRolesDeclared(block) {
  * 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.
+ *
+ * `app/<application-id>/<key>` pins a capability an Application defines in
+ * `sequence.app.yml`. It needn't exist yet (members deploy first) and counts
+ * only while the host is a member of that Application.
  */
-export const CUSTOM_CAPABILITY_PIN_RE = /^(?:org\/)?[a-z0-9-]+$/;
+export const CUSTOM_CAPABILITY_PIN_RE = /^(?:org\/|app\/[a-z][a-z0-9-]{0,63}\/)?[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-]+'))
+    .array(z.string().min(1).max(140).regex(CUSTOM_CAPABILITY_PIN_RE, 'Pins must be "org/<key>", "app/<application-id>/<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 };
+    if (pin.startsWith('org/'))
+        return { scope: 'org', key: pin.slice('org/'.length) };
+    if (pin.startsWith('app/')) {
+        const [, applicationId = '', key = ''] = pin.split('/');
+        return { scope: 'app', applicationId, key };
+    }
+    return { scope: 'project', key: pin };
 }
 /**
  * Cross-field pin validation, called from the manifest superRefine (the

package/dist/next/protocol.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { stripArtifactReleaseQuery } from './routes.js';
+import { isLoopbackHostname } from '../loopback.js';
 export const NEXT_ARTIFACT_BRIDGE_TYPE = 'artifact-studio-next';
 export const NEXT_ARTIFACT_BRIDGE_VERSION = 1;
 export const nextArtifactThemeSchema = z.object({
@@ -44,7 +45,7 @@ export function validateNextArtifactBootstrap({ bootstrap }) {
     catch {
         throw new Error('Artifact parent origin must be an exact HTTP(S) origin');
     }
-    const local = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '[::1]';
+    const local = isLoopbackHostname(parsed.hostname);
     if (parsed.origin !== bootstrap.parentOrigin || (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && local))) {
         throw new Error('Artifact parent origin must be HTTPS (or HTTP loopback), without a path');
     }

package/dist/next-dev.js

@@ -14,6 +14,7 @@ import { materializeNextPublicFonts } from './next-public-fonts-local.js';
 import { isTransientNextControlFailure, requestNextDevLease, renewNextDevLease, writeNextRuntimeFile } from './next-dev-control.js';
 import { openNextPreview, selectNextDevPort, startNextDevProcess } from './next-dev-process.js';
 import { connectLocalTunnel } from './tunnel/index.js';
+import { isLocalEnvironmentName } from './loopback.js';
 /** Shutdown never waits longer than this on Atlas; an unconfirmed session still expires with its lease. */
 const SESSION_REVOCATION_TIMEOUT_MS = 10_000;
 export async function runNextDevelopment({ root, manifest, projectId, baseUrl, environment, previewKey, port: requestedPort, links, getToken }) {
@@ -218,7 +219,7 @@ async function runTunnelConnections({ lease: initialLease, environment, port, re
         try {
             const connection = await connectLocalTunnel({
                 url: lease.tunnel.url, token: lease.tunnel.token, sessionId: lease.session.id, epoch: lease.tunnel.epoch,
-                localPort: port, publicOrigin: lease.session.publicOrigin, signal, allowInsecureLoopback: environment === 'local',
+                localPort: port, publicOrigin: lease.session.publicOrigin, signal, allowInsecureLoopback: isLocalEnvironmentName(environment),
             });
             attempt = 0;
             onStatus('ready');

package/dist/next-project.js

@@ -5,6 +5,7 @@ import { join, resolve } from 'node:path';
 import { z } from 'zod';
 import { createScrubbedChildEnv } from './child-environment.js';
 import { ARTIFACT_NEXT_APPROVED_PACKAGES } from './manifest.js';
+import { isLocalEnvironmentName, isLoopbackHostname } from './loopback.js';
 const packageSchema = z.object({
     dependencies: z.record(z.string(), z.string()).default({}),
     devDependencies: z.record(z.string(), z.string()).default({}),
@@ -42,7 +43,7 @@ export async function validateNextProject({ root, manifest, installed, nodeVersi
 }
 export function validateNextPublicOrigin({ value, environment }) {
     const url = new URL(value);
-    const local = environment === 'local' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname);
+    const local = isLocalEnvironmentName(environment) && isLoopbackHostname(url.hostname);
     if ((url.protocol !== 'https:' && !(local && url.protocol === 'http:')) || url.username || url.password || url.search || url.hash || url.pathname !== '/') {
         throw new Error('Atlas returned an invalid application origin; an exact credential-free HTTPS origin is required.');
     }

package/dist/project.js

@@ -9,7 +9,7 @@ import { readNextSourceSnapshot } from './next-source.js';
 import { normalizeArtifactPath } from './paths.js';
 const IGNORED_DIRS = new Set(['node_modules', '.git', 'dist', '.next', '.artifact-studio']);
 const TEXT_EXTENSIONS = new Set([
-    '.ts', '.tsx', '.js', '.jsx', '.json', '.css', '.html', '.md', '.yml', '.yaml', '.svg',
+    '.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.json', '.css', '.html', '.md', '.yml', '.yaml', '.svg',
 ]);
 export function hasArtifactStudioManifest(rootDir) {
     return existsSync(join(resolve(rootDir), 'artifact.bundle.yml'));
@@ -83,9 +83,9 @@ function isTextFile(path) {
         TEXT_EXTENSIONS.has(ext));
 }
 function inferContentType(path) {
-    if (path.endsWith('.tsx') || path.endsWith('.ts'))
+    if (/\.(?:tsx?|mts|cts)$/.test(path))
         return 'text/typescript';
-    if (path.endsWith('.jsx') || path.endsWith('.js'))
+    if (/\.(?:jsx?|mjs|cjs)$/.test(path))
         return 'text/javascript';
     if (path.endsWith('.css'))
         return 'text/css';

package/dist/role-definitions-notice.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Capabilities are code, roles are data: roles are created in Atlas, and
+ * `capabilities.roles.definitions` here is a deprecated one-time seed (a
+ * deploy creates any that don't exist yet and never updates them). Atlas only
+ * logs the drift, so tell the author.
+ */
+export declare function warnOnRoleDefinitions(manifest: unknown, warn?: (line: string) => void): void;

package/dist/role-definitions-notice.js

@@ -0,0 +1,19 @@
+/**
+ * Capabilities are code, roles are data: roles are created in Atlas, and
+ * `capabilities.roles.definitions` here is a deprecated one-time seed (a
+ * deploy creates any that don't exist yet and never updates them). Atlas only
+ * logs the drift, so tell the author.
+ */
+export function warnOnRoleDefinitions(manifest, warn = console.warn) {
+    // A non-null, non-array object is safe to index by key; TS can't narrow `object` to a record itself.
+    const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+    const definitions = record(record(record(record(manifest)?.capabilities)?.roles)?.definitions);
+    if (!definitions)
+        return;
+    const keys = Object.keys(definitions).sort();
+    if (keys.length === 0)
+        return;
+    warn(`[seq-studio] artifact.bundle.yml defines roles (${keys.join(', ')}). Roles in YAML are a deprecated one-time seed: ` +
+        `a deploy creates any that don't exist yet and never updates them after. Create and edit roles in Atlas ` +
+        `(Permissions → Roles); keep capabilities in YAML.`);
+}

package/dist/runtime-contracts.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { ARTIFACT_NEXT_RUNTIME, artifactNextSecretNameSchema } from './manifest-next.js';
 import { MAX_STUDIO_PATH_LENGTH } from './paths.js';
+import { isLoopbackHostname } from './loopback.js';
 export { resolveArtifactNextImages } from './next-image-config.js';
 /** Shared by local collection, repository collection and the bounded source-upload API. */
 export const ARTIFACT_NEXT_SOURCE_LIMITS = Object.freeze({
@@ -42,7 +43,7 @@ export const artifactSourcePathSchema = z.string().min(1).max(MAX_STUDIO_PATH_LE
 export const artifactRuntimeOriginSchema = z.string().max(2048).refine((value) => {
     try {
         const url = new URL(value);
-        return url.protocol === 'https:' && url.origin === value && !url.hostname.includes('*');
+        return (url.protocol === 'https:' || (url.protocol === 'http:' && isLoopbackHostname(url.hostname))) && url.origin === value && !url.hostname.includes('*');
     }
     catch {
         return false;

package/dist/sandbox-lint.js

@@ -42,7 +42,7 @@ const RULES = [
         message: "Direct fetch() to an external origin is blocked (CSP connect-src 'self') — call Atlas routes via seq.api.fetch.",
     },
 ];
-const LINTABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.css', '.html']);
+const LINTABLE_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs', '.css', '.html']);
 function extensionOf(path) {
     return path.includes('.') ? path.slice(path.lastIndexOf('.')) : '';
 }

package/dist/sdk-orm.d.ts

@@ -0,0 +1,18 @@
+import { type OperationExecutor } from '@sequenceholdings/orm/client';
+import { type SequenceApi } from './sdk.js';
+export interface ArtifactOrmExecutorConfig {
+    namespace: string;
+    /** The generated operations.manifest.json, validated before any host call. */
+    manifest: unknown;
+    /** Optional action-scoped host client (for example, withTraceAction's client). */
+    sdk?: {
+        api: Pick<SequenceApi, 'fetch'>;
+    };
+}
+/**
+ * Execute persisted operations as the signed-in Artifact user. The host owns
+ * authentication; this helper never obtains or exposes browser credentials.
+ * Declare the namespace path in capabilities.api.write (queries also use POST).
+ * Namespace grants, capabilities, row policies, and write checks still apply.
+ */
+export declare function createArtifactOrmExecutor({ namespace, manifest, sdk }: ArtifactOrmExecutorConfig): OperationExecutor;

package/dist/sdk-orm.js

@@ -0,0 +1,21 @@
+import { createOperationExecutorWithTransport, OrmClientError } from '@sequenceholdings/orm/client';
+import { seq } from './sdk.js';
+/**
+ * Execute persisted operations as the signed-in Artifact user. The host owns
+ * authentication; this helper never obtains or exposes browser credentials.
+ * Declare the namespace path in capabilities.api.write (queries also use POST).
+ * Namespace grants, capabilities, row policies, and write checks still apply.
+ */
+export function createArtifactOrmExecutor({ namespace, manifest, sdk = seq }) {
+    if (!sdk || typeof sdk.api?.fetch !== 'function') {
+        throw new OrmClientError('Artifact ORM requires the authenticated Artifact Studio host; open the deployed artifact or its Preview');
+    }
+    return createOperationExecutorWithTransport({
+        namespace,
+        manifest,
+        transport: ({ namespace: target, op, variables }) => sdk.api.fetch(`/api/data/v2/${target}`, {
+            method: 'POST',
+            body: { op, variables },
+        }),
+    });
+}

package/dist/sdk.d.ts

@@ -1,4 +1,5 @@
 import { type StartStorageUpload, type StorageUploadSession } from '@sequenceholdings/storage';
+export { createArtifactOrmExecutor, type ArtifactOrmExecutorConfig } from './sdk-orm.js';
 export interface SequenceStorageOptions {
     signal?: AbortSignal;
     timeoutMs?: number;

package/dist/sdk.js

@@ -1,4 +1,5 @@
 import { storageClient } from '@sequenceholdings/storage';
+export { createArtifactOrmExecutor } from './sdk-orm.js';
 export const seq = typeof window !== 'undefined'
     ? window.seq
     : undefined;

package/dist/server/request-context.js

@@ -1,5 +1,6 @@
 import { createPublicKey, verify } from 'node:crypto';
 import { z } from 'zod';
+import { isLoopbackHostname } from '../loopback.js';
 export const ARTIFACT_REQUEST_CONTEXT_HEADER = 'x-sequence-artifact-context';
 export const ARTIFACT_RUNTIME_TOKEN_HEADER = 'x-sequence-artifact-runtime';
 export const ARTIFACT_SERVER_REQUEST_PATH = '/api/artifact-studio/server/request';
@@ -9,7 +10,7 @@ const originSchema = z.string().max(2048).refine(value => {
     try {
         const url = new URL(value);
         return value === url.origin && (url.protocol === 'https:' ||
-            (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+            (url.protocol === 'http:' && isLoopbackHostname(url.hostname)));
     }
     catch {
         return false;

package/dist/server/runtime-config.js

@@ -2,11 +2,12 @@ import { constants } from 'node:fs';
 import { open } from 'node:fs/promises';
 import { z } from 'zod';
 import { ARTIFACT_REQUEST_CONTEXT_HEADER, verifyArtifactRequestContext } from './request-context.js';
+import { isLoopbackHostname } from '../loopback.js';
 const atlasOrigin = z.string().refine(value => {
     try {
         const url = new URL(value);
         return value === url.origin && (url.protocol === 'https:' ||
-            (url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname)));
+            (url.protocol === 'http:' && isLoopbackHostname(url.hostname)));
     }
     catch {
         return false;

package/dist/templates/react-vite/AGENTS.md

@@ -22,7 +22,7 @@ This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend
 
 ## Prerequisite
 
-None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
+None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to the CLI-pinned SDK, whose `seq` export uses the host-injected `window.seq`. The SDK also provides `createArtifactOrmExecutor({ namespace, manifest })` for persisted ORM operations; declare `/api/data/v2/<namespace>` under `capabilities.api.write`, including queries (execution uses POST). The helper handles the ORM envelope; do not pass its result to the CRM `unwrap()` helper. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
 
 ## Package manager
 

package/dist/templates/react-vite/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.3.0",
+    "@sequenceholdings/artifact-studio": "^0.4.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",

package/dist/tunnel/client.js

@@ -3,14 +3,21 @@ import WebSocket from 'ws';
 import { TunnelPeer, tunnelLimits } from './peer.js';
 import { assertSafeRequest, normalizePublicOrigin, parseTunnelFrame, sanitizeRequestHeaders, sanitizeResponseHeaders, TUNNEL_PROTOCOL } from './protocol.js';
 import { forwardWebSocketMessages, MessageBudget, permittedCloseCode, sendWebSocket, WebSocketMessage, writeChunk } from './io.js';
+import { isLoopbackHostname } from '../loopback.js';
 /** One connection/epoch only. The caller obtains a fresh lease to reconnect;
  * no HTTP request or mutation is ever retained or replayed. */
 export async function connectLocalTunnel(options) {
     const endpoint = new URL(options.url);
-    const insecureLocal = endpoint.protocol === 'ws:' && ['127.0.0.1', '[::1]', 'localhost'].includes(endpoint.hostname) && options.allowInsecureLoopback;
+    const insecureLocal = endpoint.protocol === 'ws:' && isLoopbackHostname(endpoint.hostname) && options.allowInsecureLoopback;
     if ((endpoint.protocol !== 'wss:' && !insecureLocal) || endpoint.username || endpoint.password || endpoint.hash) {
         throw new Error('Tunnel endpoint must use authenticated WSS');
     }
+    // A cleartext tunnel carries the bearer credential, so a localhost name is dialed at the loopback
+    // address browsers use for it, never through a resolver that could route it elsewhere. The Host
+    // header keeps the name the gateway validates.
+    const dial = new URL(endpoint);
+    if (insecureLocal && !['127.0.0.1', '[::1]'].includes(endpoint.hostname))
+        dial.hostname = '127.0.0.1';
     if (!Number.isSafeInteger(options.localPort) || options.localPort < 1 || options.localPort > 65535)
         throw new Error('Invalid loopback port');
     if (!Number.isSafeInteger(options.epoch) || options.epoch < 1 || !options.sessionId || !options.token || /[\r\n]/.test(options.token))
@@ -18,8 +25,8 @@ export async function connectLocalTunnel(options) {
     const publicOrigin = normalizePublicOrigin(options.publicOrigin);
     const limits = tunnelLimits(options.limits);
     options.signal?.throwIfAborted();
-    const socket = new WebSocket(endpoint, [TUNNEL_PROTOCOL], {
-        headers: { authorization: `Bearer ${options.token}`, 'x-artifact-session-id': options.sessionId, 'x-artifact-tunnel-epoch': String(options.epoch) },
+    const socket = new WebSocket(dial, [TUNNEL_PROTOCOL], {
+        headers: { host: endpoint.host, authorization: `Bearer ${options.token}`, 'x-artifact-session-id': options.sessionId, 'x-artifact-tunnel-epoch': String(options.epoch) },
         maxPayload: limits.maxFrameBytes,
         perMessageDeflate: false,
         followRedirects: false,

package/dist/tunnel/protocol.js

@@ -1,5 +1,6 @@
 import { Buffer } from 'node:buffer';
 import { z } from 'zod';
+import { isLoopbackHostname } from '../loopback.js';
 /** Version 1 is negotiated by the tunnel connection, not by individual streams. */
 export const TUNNEL_PROTOCOL = 'artifact-tunnel.v1';
 export const DEFAULT_TUNNEL_LIMITS = Object.freeze({
@@ -127,7 +128,7 @@ export function encodeTunnelFrame(frame) {
 }
 export function normalizePublicOrigin(value) {
     const url = new URL(value);
-    const isLoopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    const isLoopback = isLoopbackHostname(url.hostname);
     if (!/^https?:\/\/[^/?#@\\\s]+\/?$/i.test(value) || url.username || url.password || url.search || url.hash ||
         url.pathname !== '/' || (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback)))
         throw new Error('Tunnel public origin must be an HTTPS origin or HTTP loopback origin');

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "SDK types and CLI library for building Artifact Studio apps. Driven via `seq-studio artifact <sub>` (@sequenceholdings/studio-cli), which runs the `./cli` runCli export.",
   "type": "module",
   "exports": {
@@ -148,7 +148,7 @@
     "parse5": "7.3.0",
     "@sequenceholdings/lattice-form-renderer": "0.1.3",
     "@sequenceholdings/storage": "0.1.0",
-    "@sequenceholdings/orm": "2.1.0"
+    "@sequenceholdings/orm": "2.1.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/templates/react-vite/AGENTS.md

@@ -22,7 +22,7 @@ This is a sandboxed iframe SPA that runs inside Atlas and talks to Atlas backend
 
 ## Prerequisite
 
-None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to a virtual `window.seq` module. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
+None — `seq-studio artifact init <dir>` works from any directory; no monorepo checkout is required. The template lists `@sequenceholdings/artifact-studio` and `@sequenceholdings/atlas-ui` in **devDependencies** for local editor/type-check tooling only. `seq-studio artifact build|deploy` bundles against the CLI's own pinned copies of `react`, `react-dom`, `@tanstack/react-query`, `react-router-dom`, `sonner`, and `@sequenceholdings/atlas-ui`, and resolves `@sequenceholdings/artifact-studio` to the CLI-pinned SDK, whose `seq` export uses the host-injected `window.seq`. The SDK also provides `createArtifactOrmExecutor({ namespace, manifest })` for persisted ORM operations; declare `/api/data/v2/<namespace>` under `capabilities.api.write`, including queries (execution uses POST). The helper handles the ORM envelope; do not pass its result to the CRM `unwrap()` helper. Remote deploys (`--repo` / `--git-url`) run `pnpm install --prod` for **app-specific** `dependencies` only (e.g. `recharts`, `reactflow`) from the artifact lockfile.
 
 ## Package manager
 

package/templates/react-vite/package.json

@@ -9,7 +9,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@sequenceholdings/artifact-studio": "^0.3.0",
+    "@sequenceholdings/artifact-studio": "^0.4.0",
     "@sequenceholdings/atlas-ui": "^3.1.1",
     "@tailwindcss/postcss": "^4.2.2",
     "@tailwindcss/vite": "^4.2.2",