@forge-cms/runtime 0.5.0 → 0.6.0

package/dist/auth-managed.d.ts

@@ -0,0 +1,19 @@
+import type { OperationContext } from './context.js';
+/**
+ * Is `slug` a collection whose lifecycle the configured `AuthAdapter` owns (spec 061)? Asked of the
+ * adapter through its optional `managesCollection` — the runtime never inspects a concrete adapter or a
+ * slug convention, so an adapter that omits the method (or a composite of such adapters) restricts
+ * nothing.
+ */
+export declare function isAuthManagedCollection(ctx: OperationContext, slug: string): boolean;
+/**
+ * The generic-mutation boundary. Called first thing by `create`/`update`/`deleteDocumentInternal`/
+ * `restoreVersion` — before hooks, access checks and any read or write — so the answer is the same for
+ * every caller (`overrideAccess: true` bypasses *authorization*, never the auth subsystem's
+ * data-integrity invariants) and for a document that does not exist, and a refusal has no side effects.
+ * The message deliberately does not distinguish create/update/delete — the boundary is the same for all
+ * three, and the caller's fix (use the auth adapter's own operations) does not depend on which one this
+ * was.
+ */
+export declare function assertNotAuthManaged(ctx: OperationContext, slug: string): void;
+//# sourceMappingURL=auth-managed.d.ts.map

package/dist/auth-managed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-managed.d.ts","sourceRoot":"","sources":["../src/auth-managed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEpF;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAE9E"}

package/dist/auth-managed.js

@@ -0,0 +1,24 @@
+import { AuthManagedCollectionError } from './errors.js';
+/**
+ * Is `slug` a collection whose lifecycle the configured `AuthAdapter` owns (spec 061)? Asked of the
+ * adapter through its optional `managesCollection` — the runtime never inspects a concrete adapter or a
+ * slug convention, so an adapter that omits the method (or a composite of such adapters) restricts
+ * nothing.
+ */
+export function isAuthManagedCollection(ctx, slug) {
+    return ctx.adapters.auth.managesCollection?.(slug) === true;
+}
+/**
+ * The generic-mutation boundary. Called first thing by `create`/`update`/`deleteDocumentInternal`/
+ * `restoreVersion` — before hooks, access checks and any read or write — so the answer is the same for
+ * every caller (`overrideAccess: true` bypasses *authorization*, never the auth subsystem's
+ * data-integrity invariants) and for a document that does not exist, and a refusal has no side effects.
+ * The message deliberately does not distinguish create/update/delete — the boundary is the same for all
+ * three, and the caller's fix (use the auth adapter's own operations) does not depend on which one this
+ * was.
+ */
+export function assertNotAuthManaged(ctx, slug) {
+    if (isAuthManagedCollection(ctx, slug))
+        throw new AuthManagedCollectionError(slug);
+}
+//# sourceMappingURL=auth-managed.js.map

package/dist/auth-managed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-managed.js","sourceRoot":"","sources":["../src/auth-managed.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAqB,EAAE,IAAY;IACzE,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,iBAAiB,EAAE,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAqB,EAAE,IAAY;IACtE,IAAI,uBAAuB,CAAC,GAAG,EAAE,IAAI,CAAC;QAAE,MAAM,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC;AACrF,CAAC"}

package/dist/concurrency.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A compare-and-set on `updated_at` is only as fine as the millisecond the adapters stamp. Before a CAS
+ * write, wait until the clock has passed the stamp that was read, so this write's own stamp is strictly
+ * later: a concurrent CAS writer that read the same row then cannot match it (spec 066 review). Bounded:
+ * at most a few milliseconds. Clock skew *between* processes is outside what this can see.
+ */
+export declare function afterStamp(stamp: unknown): Promise<void>;
+//# sourceMappingURL=concurrency.d.ts.map

package/dist/concurrency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.d.ts","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9D"}

package/dist/concurrency.js

@@ -0,0 +1,15 @@
+/**
+ * A compare-and-set on `updated_at` is only as fine as the millisecond the adapters stamp. Before a CAS
+ * write, wait until the clock has passed the stamp that was read, so this write's own stamp is strictly
+ * later: a concurrent CAS writer that read the same row then cannot match it (spec 066 review). Bounded:
+ * at most a few milliseconds. Clock skew *between* processes is outside what this can see.
+ */
+export async function afterStamp(stamp) {
+    const seen = typeof stamp === 'string' ? Date.parse(stamp) : NaN;
+    if (Number.isNaN(seen))
+        return;
+    for (let i = 0; i < 20 && Date.now() <= seen; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+    }
+}
+//# sourceMappingURL=concurrency.js.map

package/dist/concurrency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrency.js","sourceRoot":"","sources":["../src/concurrency.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAc;IAC7C,MAAM,IAAI,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACjE,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO;IAC/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

package/dist/context.d.ts

@@ -12,5 +12,10 @@ export interface OperationContext {
     getCollection(slug: string): CollectionDefinition | undefined;
     getGlobal(slug: string): GlobalDefinition | undefined;
     getCollections(): readonly CollectionDefinition[];
+    /**
+     * Every registered global. Optional so a structural implementation written before spec 064 still
+     * type-checks; without it, relation integrity cannot see references held by globals.
+     */
+    getGlobals?(): readonly GlobalDefinition[];
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAC9D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACtD,cAAc,IAAI,SAAS,oBAAoB,EAAE,CAAC;CACnD"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IAC9D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IACtD,cAAc,IAAI,SAAS,oBAAoB,EAAE,CAAC;IAClD;;;OAGG;IACH,UAAU,CAAC,IAAI,SAAS,gBAAgB,EAAE,CAAC;CAC5C"}

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import type { ValidationError } from '@forge-cms/core';
-export type ForgeErrorCode = 'NOT_FOUND' | 'INVALID_INPUT' | 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'UNKNOWN_FIELD' | 'INVALID_QUERY' | 'UNIQUE_CONSTRAINT' | 'INTERNAL_ERROR';
+export type ForgeErrorCode = 'NOT_FOUND' | 'INVALID_INPUT' | 'VALIDATION_ERROR' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'UNKNOWN_FIELD' | 'INVALID_QUERY' | 'UNIQUE_CONSTRAINT' | 'AUTH_MANAGED_COLLECTION' | 'CONCURRENT_MODIFICATION' | 'INTERNAL_ERROR';
 export declare class ForgeError extends Error {
     readonly status: number;
     readonly code: ForgeErrorCode;
@@ -47,6 +47,34 @@ export declare class UniqueConstraintError extends ForgeError {
     readonly fields: string[];
     constructor(collection: string, fields: string[]);
 }
+/**
+ * A generic `create`/`update`/`delete` targeted a collection whose lifecycle the configured
+ * `AuthAdapter` owns (`AuthAdapter.managesCollection`, spec 061). Those mutations would bypass the
+ * adapter's invariants — first-admin provisioning, last-admin protection, password hashing, email
+ * normalisation, session versioning — so they are refused for every caller, trusted (`overrideAccess:
+ * true`) or not. Deliberately says nothing about which adapter or how; the way out is the auth
+ * adapter's own user-management operations.
+ */
+export declare class AuthManagedCollectionError extends ForgeError {
+    readonly collection: string;
+    constructor(collection: string);
+}
+/**
+ * A versioned document mutation lost a race (spec 062): another write committed a new version of the
+ * same document after this one read it, so this one's document write and snapshot were rolled back
+ * together — nothing was written. Forge never retries it automatically (`before*` hooks may already
+ * have run); re-read the document and submit again. Deliberately names the public collection slug,
+ * never the internal `_versions_*` table whose unique index detected the conflict.
+ *
+ * Spec 064 reuses it for relation lifecycle conflicts — a referenced document deleted while a write was
+ * in progress, or a relation delete whose graph changed before it committed — with a `message` saying
+ * so. The meaning is the same: another request changed what this one depended on; nothing was written.
+ */
+export declare class ConcurrentModificationError extends ForgeError {
+    readonly collection: string;
+    readonly id: string;
+    constructor(collection: string, id: string, message?: string);
+}
 export declare function isForgeError(err: unknown): err is ForgeError;
 export interface ForgeApiErrorBody {
     error: {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,eAAe,GACf,kBAAkB,GAClB,cAAc,GACd,WAAW,GACX,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,gBAAgB,CAAC;AAErB,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc;CAMlE;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;gBAExB,OAAO,EAAE,eAAe,EAAE;CAIvC;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,SAAiB;CAGrC;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,SAAc;CAGlC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,UAAU;gBAC3B,OAAO,SAAgC;CAGpD;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;CAWjD;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAE5D;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE;QACL,IAAI,EAAE,cAAc,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAyBjE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,eAAe,GACf,kBAAkB,GAClB,cAAc,GACd,WAAW,GACX,eAAe,GACf,eAAe,GACf,mBAAmB,GACnB,yBAAyB,GACzB,yBAAyB,GACzB,gBAAgB,CAAC;AAErB,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc;CAMlE;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,OAAO,EAAE,eAAe,EAAE,CAAC;gBAExB,OAAO,EAAE,eAAe,EAAE;CAIvC;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,SAAiB;CAGrC;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,SAAc;CAGlC;AAED;;;;;GAKG;AACH,qBAAa,SAAU,SAAQ,UAAU;gBAC3B,OAAO,SAAgC;CAGpD;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,UAAU;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;gBAEd,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;CAWjD;AAED;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,UAAU;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM;CAS/B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,2BAA4B,SAAQ,UAAU;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;gBAER,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAW7D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU,CAE5D;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE;QACL,IAAI,EAAE,cAAc,CAAC;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;CACH;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAyBjE"}

package/dist/errors.js

@@ -73,6 +73,44 @@ export class UniqueConstraintError extends ForgeError {
         this.fields = fields;
     }
 }
+/**
+ * A generic `create`/`update`/`delete` targeted a collection whose lifecycle the configured
+ * `AuthAdapter` owns (`AuthAdapter.managesCollection`, spec 061). Those mutations would bypass the
+ * adapter's invariants — first-admin provisioning, last-admin protection, password hashing, email
+ * normalisation, session versioning — so they are refused for every caller, trusted (`overrideAccess:
+ * true`) or not. Deliberately says nothing about which adapter or how; the way out is the auth
+ * adapter's own user-management operations.
+ */
+export class AuthManagedCollectionError extends ForgeError {
+    collection;
+    constructor(collection) {
+        super(`Collection '${collection}' is managed by the configured auth adapter and cannot be mutated ` +
+            `through generic collection CRUD. Use the auth adapter's user-management operations instead.`, 403, 'AUTH_MANAGED_COLLECTION');
+        this.collection = collection;
+    }
+}
+/**
+ * A versioned document mutation lost a race (spec 062): another write committed a new version of the
+ * same document after this one read it, so this one's document write and snapshot were rolled back
+ * together — nothing was written. Forge never retries it automatically (`before*` hooks may already
+ * have run); re-read the document and submit again. Deliberately names the public collection slug,
+ * never the internal `_versions_*` table whose unique index detected the conflict.
+ *
+ * Spec 064 reuses it for relation lifecycle conflicts — a referenced document deleted while a write was
+ * in progress, or a relation delete whose graph changed before it committed — with a `message` saying
+ * so. The meaning is the same: another request changed what this one depended on; nothing was written.
+ */
+export class ConcurrentModificationError extends ForgeError {
+    collection;
+    id;
+    constructor(collection, id, message) {
+        super(message ??
+            `Document '${id}' in '${collection}' was changed by another request while this one was in ` +
+                `progress; nothing was written. Reload it and try again.`, 409, 'CONCURRENT_MODIFICATION');
+        this.collection = collection;
+        this.id = id;
+    }
+}
 export function isForgeError(err) {
     return err instanceof ForgeError;
 }

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/files.d.ts

@@ -2,7 +2,11 @@ import type { ApiContext } from '@forge-cms/api';
 import type { AnyForgeCmsRuntime } from './runtime.js';
 export interface FileHandlerOptions<TEnv = unknown> {
     runtime: AnyForgeCmsRuntime<TEnv>;
-    /** `cache-control` for a hit. Defaults to a conservative minute. */
+    /**
+     * `cache-control` for a hit served to an **anonymous** caller. Defaults to a conservative minute. A
+     * hit for an authenticated caller is always `private, no-store` (spec 067): shared caches must not
+     * hand a file one user may read to another who may not.
+     */
     cacheControl?: string;
 }
 /**
@@ -19,6 +23,16 @@ export interface FileHandlerOptions<TEnv = unknown> {
  *   handleFile({ request: toWebRequest(event), params: { key: getRouterParam(event, 'key') ?? '' } }, { runtime })
  * );
  * ```
+ *
+ * **Access (spec 067).** A file is served only as part of the upload document that owns it: the document
+ * of the key's collection whose Forge-recorded `_storageKey` is this key. That document must be readable
+ * by the caller through the normal read pipeline (collection and row access, draft visibility), exactly
+ * as the Local API `findByID` with `overrideAccess: false` allows. It applies the collection's own
+ * `access.read`, **not** route-level options such as `requireAuth`/`allowedRoles` — a collection
+ * whose reads are gated only at its route must declare `access.read` to gate its files too. A key no
+ * document owns, or one whose document the
+ * caller cannot read, is the same `404` — it confirms nothing. A public bucket or CDN URL is outside
+ * this handler and outside Forge's access control.
  */
 export declare function handleFile<TEnv = unknown>(context: ApiContext<TEnv>, options: FileHandlerOptions<TEnv>): Promise<Response>;
 //# sourceMappingURL=files.d.ts.map

package/dist/files.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD,MAAM,WAAW,kBAAkB,CAAC,IAAI,GAAG,OAAO;IAChD,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAClC,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAG,OAAO,EAC7C,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,EACzB,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CAkCnB"}
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAKvD,MAAM,WAAW,kBAAkB,CAAC,IAAI,GAAG,OAAO;IAChD,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAG,OAAO,EAC7C,OAAO,EAAE,UAAU,CAAC,IAAI,CAAC,EACzB,OAAO,EAAE,kBAAkB,CAAC,IAAI,CAAC,GAChC,OAAO,CAAC,QAAQ,CAAC,CA8CnB"}

package/dist/files.js

@@ -1,3 +1,6 @@
+import { AccessDeniedError, NotFoundError } from './errors.js';
+import { resolveOptionalUser } from './handlers.js';
+import { findStorageOwner } from './storage-intents.js';
 /**
  * Serves a stored file back over HTTP.
  *
@@ -12,35 +15,73 @@
  *   handleFile({ request: toWebRequest(event), params: { key: getRouterParam(event, 'key') ?? '' } }, { runtime })
  * );
  * ```
+ *
+ * **Access (spec 067).** A file is served only as part of the upload document that owns it: the document
+ * of the key's collection whose Forge-recorded `_storageKey` is this key. That document must be readable
+ * by the caller through the normal read pipeline (collection and row access, draft visibility), exactly
+ * as the Local API `findByID` with `overrideAccess: false` allows. It applies the collection's own
+ * `access.read`, **not** route-level options such as `requireAuth`/`allowedRoles` — a collection
+ * whose reads are gated only at its route must declare `access.read` to gate its files too. A key no
+ * document owns, or one whose document the
+ * caller cannot read, is the same `404` — it confirms nothing. A public bucket or CDN URL is outside
+ * this handler and outside Forge's access control.
  */
 export async function handleFile(context, options) {
     const raw = context.params?.['key'];
-    if (!raw) {
-        return new Response(JSON.stringify({ error: 'Missing file key' }), {
-            status: 400,
-            headers: { 'content-type': 'application/json' }
-        });
+    if (!raw)
+        return json({ error: 'Missing file key' }, 400);
+    let key;
+    try {
+        key = decodeURIComponent(raw);
+    }
+    catch {
+        return json({ error: 'Malformed file key' }, 400);
     }
-    const key = decodeURIComponent(raw);
+    const { runtime } = options;
     try {
-        const object = await options.runtime.adapters.storage.get(key);
-        if (!object?.body) {
-            return new Response(JSON.stringify({ error: `File '${key}' not found` }), {
-                status: 404,
-                headers: { 'content-type': 'application/json' }
+        const owner = await findStorageOwner(runtime, key);
+        if (!owner)
+            return notFound(key);
+        const user = await resolveOptionalUser(context, runtime);
+        try {
+            await runtime.findByID({
+                collection: owner.collection,
+                id: owner.id,
+                user,
+                overrideAccess: false,
+                depth: 0
             });
         }
+        catch (err) {
+            if (err instanceof NotFoundError || err instanceof AccessDeniedError)
+                return notFound(key);
+            throw err;
+        }
+        const object = await runtime.adapters.storage.get(key);
+        if (!object?.body)
+            return notFound(key);
         return new Response(object.body, {
             status: 200,
             headers: {
                 'content-type': object.contentType ?? 'application/octet-stream',
-                'cache-control': options.cacheControl ?? 'public, max-age=60',
+                'cache-control': user === null ? (options.cacheControl ?? 'public, max-age=60') : 'private, no-store',
                 ...(object.size !== undefined && { 'content-length': String(object.size) })
             }
         });
     }
-    catch (err) {
-        return new Response(JSON.stringify({ error: err instanceof Error ? err.message : 'Failed to read file' }), { status: 500, headers: { 'content-type': 'application/json' } });
+    catch {
+        // No driver or storage message reaches the client (it can name buckets, tables or credentials).
+        return json({ error: 'Failed to read file' }, 500);
     }
 }
+function notFound(key) {
+    return json({ error: `File '${key}' not found` }, 404);
+}
+/** Error bodies are never cached: an anonymous `404` must not be served to the owner who may read it. */
+function json(body, status) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' }
+    });
+}
 //# sourceMappingURL=files.js.map

package/dist/files.js.map

@@ -1 +1 @@
-{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAyB,EACzB,OAAiC;IAEjC,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;YACjE,MAAM,EAAE,GAAG;YACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;SAChD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,GAAG,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC;YAClB,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,SAAS,GAAG,aAAa,EAAE,CAAC,EAAE;gBACxE,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;aAChD,CAAC,CAAC;QACL,CAAC;QAED,OAAO,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE;YAC/B,MAAM,EAAE,GAAG;YACX,OAAO,EAAE;gBACP,cAAc,EAAE,MAAM,CAAC,WAAW,IAAI,0BAA0B;gBAChE,eAAe,EAAE,OAAO,CAAC,YAAY,IAAI,oBAAoB;gBAC7D,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;aAC5E;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,IAAI,QAAQ,CACjB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,qBAAqB,EAAE,CAAC,EACrF,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CACjE,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"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"}

package/dist/globals.d.ts

@@ -1,4 +1,4 @@
-import type { CmsUser } from '@forge-cms/core';
+import type { CmsUser, GlobalDefinition } from '@forge-cms/core';
 import type { DatabaseRecord } from '@forge-cms/db';
 import type { OperationContext } from './context.js';
 export interface GlobalBaseArgs {
@@ -8,17 +8,35 @@ export interface GlobalBaseArgs {
 }
 export interface GetGlobalArgs extends GlobalBaseArgs {
     depth?: 0 | 1;
+    /** Resolve `localized` fields to this locale (with fallback), for a global declaring `locales` (spec 066). */
+    locale?: string;
 }
 export interface UpdateGlobalArgs extends GlobalBaseArgs {
     data: Record<string, unknown>;
+    /** Write `localized` fields into this locale only, keeping the others (spec 066). Must be one of the global's `locales`. */
+    locale?: string;
 }
+/**
+ * The global options that exist on the shared collection types but can never apply to a singleton that
+ * is never created through `create` nor deleted (spec 066): delete hooks, and `create`/`delete` access
+ * rules. Refused at startup instead of being accepted and silently ignored. One message per problem.
+ * (Localized fields of globals are checked with collections', by `validateLocalizationSchema`.)
+ */
+export declare function validateGlobalSchema(globals: readonly GlobalDefinition[]): string[];
 /**
  * Reads the singleton global document. Returns `null` if the global has never been written.
  */
 export declare function getGlobal(ctx: OperationContext, args: GetGlobalArgs): Promise<DatabaseRecord | null>;
 /**
- * Creates or updates the singleton global document. Unlike collections, globals always have
- * exactly one document — the first write creates it, subsequent writes update it.
+ * Creates or updates the singleton global document. Unlike collections, globals always have exactly one
+ * document — the first write creates it, later writes update it.
+ *
+ * Later writes are **partial**, exactly like a collection `update()` (spec 066): omitted fields keep
+ * their stored values (defaults and the draft status apply to the first write only), validation runs on
+ * the merged document, and a `locale` write changes that locale of each `localized` field and keeps the
+ * others. A query-returning `access.update` rule must match the stored row, and cannot authorize the
+ * first write (there is no row to match). Two simultaneous first writes: one commits, the other gets
+ * `409 CONCURRENT_MODIFICATION` with nothing written.
  */
 export declare function updateGlobal(ctx: OperationContext, args: UpdateGlobalArgs): Promise<DatabaseRecord>;
 //# sourceMappingURL=globals.d.ts.map

package/dist/globals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAoB,MAAM,iBAAiB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AA0BrD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;CACf;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AA6ED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAmDhC;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAsGzB"}
+{"version":3,"file":"globals.d.ts","sourceRoot":"","sources":["../src/globals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAwB,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,KAAK,EAAwB,cAAc,EAAiB,MAAM,eAAe,CAAC;AAKzF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAuCrD,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,WAAW,aAAc,SAAQ,cAAc;IACnD,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACd,8GAA8G;IAC9G,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,4HAA4H;IAC5H,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAsBnF;AAiGD;;GAEG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA+DhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,CAyJzB"}