@sequenceholdings/artifact-studio 0.6.6 → 0.6.7

package/README.md

@@ -17,7 +17,7 @@ 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`:
+For a static (schema-v1) artifact, declare the exact namespace path in `artifact.bundle.yml`:
 
 ```yaml
 capabilities:
@@ -25,7 +25,7 @@ capabilities:
     write: ['/api/data/v2/team_directory']
 ```
 
-Persisted queries and mutations both use POST, so both require this `write`
+In that runtime, 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
@@ -36,10 +36,77 @@ 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. The adapter never retries a call automatically. For
-several operations in one traced UI action, pass `withTraceAction`'s client as
+instead of reporting saved data. The adapter never retries a call automatically. On the
+static runtime, for several operations in one traced UI action, pass `withTraceAction`'s client as
 the optional `sdk` argument.
 
+### Next.js browser ORM admission (internal prerelease)
+
+The following schema-v2 manifest controls are planned for Artifact Studio 0.6.7
+and Studio CLI 0.4.7. They require the matching platform deployment as well as
+the SDK/CLI release; workspace source and version numbers alone do not establish
+published availability. The Next.js runtime remains an internal, opt-in Preview
+surface.
+
+For a Next.js artifact, declare browser table reach and optionally restrict the
+persisted operations and artifact capabilities required to use that reach:
+
+```yaml
+capabilities:
+  roles:
+    capabilities:
+      directory-reader:
+        description: Read the team directory in this application
+  data:
+    read: [team_directory/profiles]
+    write: []
+    operations: [team_directory/ops/Profiles]
+    required_capabilities:
+      team_directory: [directory-reader]
+```
+
+`operations` accepts at most 256 exact `namespace/ops/Operation` references;
+wildcards are not accepted. Omitting it preserves existing table-based
+admission. An explicit `operations: []` denies every browser ORM operation.
+Listing an operation does not replace its `data.read` or `data.write` reach:
+queries still need every table they read, and mutations still need write reach.
+The Next.js host routes ORM requests through this data contract; no additional
+API path declaration is needed. The POST transport does not grant mutation authority.
+
+The allowlist admits registered persisted operations only. Autogenerated
+`DatasetPreview_*` hashes are excluded even if a registered operation has the
+same name. Operation admission retains the existing active and previous
+operation-set fallback; the allowlist pins names, not one content hash. Give a
+security-tightened replacement query a new operation name and remove the old
+name from the allowlist, otherwise a retained older hash with that name can
+remain admissible.
+
+`required_capabilities` maps a source namespace to a nonempty list of artifact
+capability pins. Every listed pin is required, and each must be declared in
+`capabilities.uses` or, for a local bare key, defined under
+`capabilities.roles.capabilities`. Pins use the existing bare `<key>`,
+`org/<key>`, or `app/<application-id>/<key>` grammar. Each namespace in either control must
+also be reached by browser `data.read` or `data.write`. Preview bindings retain
+the source namespace keys in these declarations.
+
+The platform checks the persisted manifest against the authenticated user's
+current artifact capability claims before ORM delegation. Caller-provided
+claims and UI checks cannot satisfy the requirement. Namespace runtime grants,
+operation capability checks, and row/write policies still apply independently;
+these declarations grant no access. They constrain only Next.js browser ORM
+requests, not server SDK calls or external ingress, which keep their own
+declarations and authorization. They also do not transitively restrict ORM
+work inside Managed Functions or general API calls; those surfaces enforce
+their own permission contracts. The `createArtifactOrmExecutor` API is
+unchanged.
+
+For request correlation, the original `seq.api.fetch` response envelope includes
+an `x-request-id` header after browser authorization succeeds, including later
+denials. The platform generates this ID and records it in the browser admission
+audit; it never uses an iframe-supplied ID. Authentication failures have no
+browser admission ID. The ORM executor still returns the operation data, so
+capture the fetch envelope when support tooling needs this correlation value.
+
 ### Exact numbers
 
 By default `numeric` and `bigint` values come back as JSON numbers, which

package/VERSION-PIN.md

@@ -112,6 +112,28 @@ entry points, which remain classified **internal**. They add no package export
 subpath or supported direct HTTP surface. Publication and a reviewed public
 contract decision are separate from local build verification.
 
+## Planned browser ORM admission release
+
+Artifact Studio 0.6.7 and Studio CLI 0.4.7 are the planned package pair for
+schema-v2 Next.js browser `capabilities.data.operations` and
+`capabilities.data.required_capabilities`. Atlas UI stays pinned at 3.4.1.
+Publish the SDK and downstream CLI through the normal chain release, and
+deploy the matching platform support before using these controls. This note
+records the intended release; it is not evidence of npm publication or
+environment rollout. The Next.js manifest/runtime surfaces remain internal.
+
+Older schema-v2 parsers reject the new keys. Existing manifests that omit them
+keep table-based browser admission. An empty `operations` list instead denies
+all browser ORM operations; a nonempty list names exact persisted operations.
+Namespace-scoped `required_capabilities` adds an all-of artifact capability
+check to the existing namespace grants and row/write policies. These controls
+do not change server SDK or external-ingress admission or transitively restrict
+Managed Functions and general API calls. The executor API is unchanged.
+Operation names retain active/previous persisted-operation fallback, so a
+security-tightened query needs a fresh name to exclude retained older hashes;
+autogenerated preview hashes never qualify. See the SDK README for the full
+declaration contract and source-namespace preview behavior.
+
 ## What this means
 
 `shared/services/artifact-studio/src/build.ts` force-aliases platform peers via

package/dist/manifest-next-browser-data.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+import { type ArtifactStudioCustomRoles } from './manifest-custom-roles.js';
+/** Additional browser admission rules; neither these rules nor data reach grant access. */
+export declare const artifactNextBrowserDataSchema: z.ZodPrefault<z.ZodObject<{
+    operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    required_capabilities: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+    read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>>;
+export type ArtifactNextBrowserData = z.infer<typeof artifactNextBrowserDataSchema>;
+/** Restriction references must be backed by this browser's reach and declared artifact pins. */
+export declare function validateBrowserDataAdmission({ data, uses, roles, ctx }: {
+    data: ArtifactNextBrowserData;
+    uses: readonly string[];
+    roles?: ArtifactStudioCustomRoles;
+    ctx: z.RefinementCtx;
+}): void;

package/dist/manifest-next-browser-data.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { capabilityPinsSchema } from './manifest-custom-roles.js';
+import { boundedRef, ormOperationRef, reachShape } from './manifest-next-reach.js';
+const browserOperationRef = boundedRef.refine((ref) => ormOperationRef.test(ref), 'Browser ORM operations name each operation: namespace/ops/Operation');
+/** Additional browser admission rules; neither these rules nor data reach grant access. */
+export const artifactNextBrowserDataSchema = z.strictObject({
+    ...reachShape.data.unwrap().shape,
+    // Preserve absence: existing manifests use table-set admission. An explicit [] denies all.
+    operations: z.array(browserOperationRef).max(256).refine((operations) => new Set(operations).size === operations.length, 'Browser ORM operations must be unique').optional(),
+    // Keys name source namespaces, before development/preview namespace bindings are applied.
+    required_capabilities: z.preprocess((value, ctx) => {
+        // Zod records skip this own key before validating keys; reject it rather than silently drop it.
+        if (value !== null && typeof value === 'object' && Object.hasOwn(value, '__proto__')) {
+            ctx.addIssue({ code: 'custom', path: ['__proto__'], message: 'Capability guard keys are ORM source namespaces' });
+        }
+        return value;
+    }, z.record(z.string().regex(/^[a-z][a-z0-9_]{0,40}$/, 'Capability guard keys are ORM source namespaces'), capabilityPinsSchema.unwrap().min(1).refine((pins) => new Set(pins).size === pins.length, 'Required browser ORM capabilities must be unique'))).optional(),
+}).prefault({});
+/** Restriction references must be backed by this browser's reach and declared artifact pins. */
+export function validateBrowserDataAdmission({ data, uses, roles, ctx }) {
+    const reached = new Set([...data.read, ...data.write].map((ref) => ref.split('/', 1)[0]));
+    for (const [index, operation] of (data.operations ?? []).entries()) {
+        const namespace = operation.split('/', 1)[0];
+        if (!reached.has(namespace)) {
+            ctx.addIssue({
+                code: 'custom', path: ['capabilities', 'data', 'operations', index],
+                message: `${operation} names a namespace that browser capabilities.data.read or write does not reach`,
+            });
+        }
+    }
+    const declared = new Set([...Object.keys(roles?.capabilities ?? {}), ...uses]);
+    for (const [namespace, pins] of Object.entries(data.required_capabilities ?? {})) {
+        const path = ['capabilities', 'data', 'required_capabilities', namespace];
+        if (!reached.has(namespace)) {
+            ctx.addIssue({ code: 'custom', path, message: `${namespace} is not reached by browser capabilities.data.read or write` });
+        }
+        for (const [index, pin] of pins.entries()) {
+            if (!declared.has(pin)) {
+                ctx.addIssue({
+                    code: 'custom', path: [...path, index],
+                    message: `Required capability "${pin}" must be declared in capabilities.roles.capabilities or capabilities.uses`,
+                });
+            }
+        }
+    }
+}

package/dist/manifest-next.d.ts

@@ -22,6 +22,7 @@ export declare const ARTIFACT_NEXT_RESOURCE_DEFAULTS: {
     timeout_seconds: number;
 };
 export { artifactNextAuditCapabilitySchema };
+export type { ArtifactNextBrowserData } from './manifest-next-browser-data.js';
 export * from './manifest-next-ingress.js';
 export declare const artifactNextServerCapabilitiesSchema: z.ZodPrefault<z.ZodObject<{
     audit: z.ZodOptional<z.ZodObject<{
@@ -228,6 +229,12 @@ export declare const artifactStudioNextManifestSchema: z.ZodObject<{
         next: z.ZodDefault<z.ZodLiteral<"16.3">>;
     }, z.core.$strict>>;
     capabilities: z.ZodPrefault<z.ZodObject<{
+        data: z.ZodPrefault<z.ZodObject<{
+            operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            required_capabilities: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         allow_downloads: z.ZodDefault<z.ZodBoolean>;
         allow_popups: z.ZodDefault<z.ZodBoolean>;
         roles: z.ZodOptional<z.ZodObject<{
@@ -247,10 +254,6 @@ export declare const artifactStudioNextManifestSchema: z.ZodObject<{
             editor: "editor";
             admin: "admin";
         }>>>;
-        data: z.ZodPrefault<z.ZodObject<{
-            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
         api: z.ZodPrefault<z.ZodObject<{
             read: z.ZodDefault<z.ZodArray<z.ZodString>>;
             write: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/manifest-next.js

@@ -1,6 +1,7 @@
 import { ontologyContractSchema } from '@sequenceholdings/orm/canonical';
 import { z } from 'zod';
 import { capabilityPinsSchema, customRolesBlockSchema, validateCapabilityPins } from './manifest-custom-roles.js';
+import { artifactNextBrowserDataSchema, validateBrowserDataAdmission } from './manifest-next-browser-data.js';
 import { isManagedServerInvokePath } from './server/managed-server-path.js';
 import { artifactNextIngressSchema, validateIngressAgainstServer } from './manifest-next-ingress.js';
 import { artifactNextAuditCapabilitySchema, reachShape, serviceAccountRef } from './manifest-next-reach.js';
@@ -25,6 +26,7 @@ const strictCustomRoles = customRolesBlockSchema.safeExtend({
 }).strict();
 const browserCapabilities = z.strictObject({
     ...reachShape,
+    data: artifactNextBrowserDataSchema,
     allow_downloads: z.boolean().default(false),
     allow_popups: z.boolean().default(false),
     roles: strictCustomRoles.optional(),
@@ -125,6 +127,7 @@ export const artifactStudioNextManifestSchema = z.strictObject({
     sidebarIcon: z.string().max(64).optional(),
     sidebarBadge: sidebarBadgeSchema.strict().optional(),
 }).superRefine((manifest, ctx) => {
+    validateBrowserDataAdmission({ ...manifest.capabilities, ctx });
     for (const message of validateCapabilityPins({ uses: manifest.capabilities.uses, roles: manifest.capabilities.roles })) {
         ctx.addIssue({ code: 'custom', path: ['capabilities', 'uses'], message });
     }

package/dist/manifest.d.ts

@@ -112,6 +112,12 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
         next: z.ZodDefault<z.ZodLiteral<"16.3">>;
     }, z.core.$strict>>;
     capabilities: z.ZodPrefault<z.ZodObject<{
+        data: z.ZodPrefault<z.ZodObject<{
+            operations: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            required_capabilities: z.ZodOptional<z.ZodPreprocess<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>>;
+            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         allow_downloads: z.ZodDefault<z.ZodBoolean>;
         allow_popups: z.ZodDefault<z.ZodBoolean>;
         roles: z.ZodOptional<z.ZodObject<{
@@ -131,10 +137,6 @@ export declare const artifactStudioManifestSchema: z.ZodUnion<readonly [z.ZodObj
             editor: "editor";
             admin: "admin";
         }>>>;
-        data: z.ZodPrefault<z.ZodObject<{
-            read: z.ZodDefault<z.ZodArray<z.ZodString>>;
-            write: z.ZodDefault<z.ZodArray<z.ZodString>>;
-        }, z.core.$strict>>;
         api: z.ZodPrefault<z.ZodObject<{
             read: z.ZodDefault<z.ZodArray<z.ZodString>>;
             write: z.ZodDefault<z.ZodArray<z.ZodString>>;

package/dist/server/internal/verify-any.d.ts

@@ -1,5 +1,19 @@
 import { type ArtifactGatewayPublicKeys, type ArtifactRequestContext, type RequestContextV2External } from '../request-context.js';
 export type AnyArtifactRequestContext = ArtifactRequestContext | RequestContextV2External;
+/**
+ * Optional human-directory prefetch for hosted admission, never an authorization result. The
+ * signed project is not yet bound to the credential's database record. After loading that record,
+ * the caller must still run its ordinary verifier with the runtime's keys and authoritative
+ * project, rechecking the clock after the await. Ineligible or invalid contexts return null so
+ * credential failures and external admission keep their existing checks and error ordering.
+ */
+export declare function preverifyHostedBrowserContext({ token, publicKeys, environment, deploymentId, now }: {
+    token: string | null;
+    publicKeys: ArtifactGatewayPublicKeys;
+    environment: string;
+    deploymentId: string;
+    now?: number;
+}): ArtifactRequestContext | null;
 /**
  * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
  * external (v2) contexts, such as the broker. Applications never get this: it is not exported

package/dist/server/internal/verify-any.js

@@ -1,7 +1,33 @@
-import { ArtifactContextError, requestContextV2ExternalSchema, } from '../request-context.js';
+import { ArtifactContextError, ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX, artifactRequestContextSchema, requestContextV2ExternalSchema, } from '../request-context.js';
 import { ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX, verifySignedContext } from './signed-token.js';
 import { parseV1Context } from './v1-context.js';
 import { canonicalizeIngressPath, signedIngressPath } from '../ingress-routes.js';
+/**
+ * Optional human-directory prefetch for hosted admission, never an authorization result. The
+ * signed project is not yet bound to the credential's database record. After loading that record,
+ * the caller must still run its ordinary verifier with the runtime's keys and authoritative
+ * project, rechecking the clock after the await. Ineligible or invalid contexts return null so
+ * credential failures and external admission keep their existing checks and error ordering.
+ */
+export function preverifyHostedBrowserContext({ token, publicKeys, environment, deploymentId, now = Math.floor(Date.now() / 1000) }) {
+    try {
+        const { kid, payload } = verifySignedContext({ token, publicKeys });
+        if (kid.startsWith(ARTIFACT_EXTERNAL_CONTEXT_KID_PREFIX))
+            return null;
+        const parsed = artifactRequestContextSchema.safeParse(payload);
+        if (!parsed.success)
+            return null;
+        const context = parsed.data;
+        if (context.mode === 'development' || context.deploymentId !== deploymentId ||
+            context.sub.startsWith(ARTIFACT_SERVICE_ACCOUNT_SUB_PREFIX))
+            return null;
+        // Self-binding is safe only for this prefetch: ordinary admission binds the stored project.
+        return parseV1Context({ payload: context, projectId: context.projectId, environment, now });
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Version-dispatching verifier for platform code that must accept both Atlas-user (v1) and
  * external (v2) contexts, such as the broker. Applications never get this: it is not exported

package/package.json

@@ -9,7 +9,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.6.6",
+  "version": "0.6.7",
   "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": {
@@ -166,9 +166,9 @@
     "google-auth-library": "^10.5.0",
     "server-only": "0.0.1",
     "parse5": "7.3.0",
-    "@sequenceholdings/lattice-form-renderer": "0.2.0",
+    "@sequenceholdings/storage": "0.1.1",
     "@sequenceholdings/orm": "2.5.0",
-    "@sequenceholdings/storage": "0.1.1"
+    "@sequenceholdings/lattice-form-renderer": "0.2.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",