@selvajs/platform 0.21.0-beta.2 → 1.0.0-beta.4

package/dist/computeServer/secrets.js

@@ -2,12 +2,19 @@ import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 const ALGO = 'aes-256-gcm';
 const IV_BYTES = 12;
 const TAG_BYTES = 16;
-const PREFIX = 'enc:v1:';
+const PREFIX_V1 = 'enc:v1:';
+const PREFIX_V2 = 'enc:v2:';
+export function isEncryptedSecret(value) {
+    return value.startsWith(PREFIX_V1) || value.startsWith(PREFIX_V2);
+}
 /**
  * AES-256-GCM envelope for at-rest secrets (e.g. compute API keys).
  *
- * Wire format: `enc:v1:<base64(iv|tag|ciphertext)>`. The version prefix lets
- * a future migration to a new algorithm tell old and new envelopes apart.
+ * Wire format: `enc:v2:<base64(iv|tag|ciphertext)>`. `v2` authenticates the
+ * record the secret belongs to as AAD, so ciphertext copied onto another record
+ * fails to decrypt instead of handing the plaintext to that record's URL.
+ * `enc:v1:` envelopes have no AAD and still read: a store rewrites them as `v2`
+ * on its next save.
  *
  * Defends against backup leaks, accidental file/DB sharing, and read-only
  * storage access — not against an attacker who also has the master key
@@ -16,11 +23,11 @@ const PREFIX = 'enc:v1:';
  *
  * Pure `node:crypto`, no fs or DB coupling, so the local and Supabase
  * compute-server stores share this one implementation.
+ *
+ * Pass `aad` to bind the secret to its record. {@link decryptSecret} then needs the
+ * same value.
  */
-export function isEncryptedSecret(value) {
-    return value.startsWith(PREFIX);
-}
-export function encryptSecret(plaintext, key) {
+export function encryptSecret(plaintext, key, aad) {
     if (key.length !== 32) {
         throw new Error(`Secret key must be 32 bytes; got ${key.length}`);
     }
@@ -29,23 +36,33 @@ export function encryptSecret(plaintext, key) {
     }
     const iv = randomBytes(IV_BYTES);
     const cipher = createCipheriv(ALGO, key, iv);
+    if (aad !== undefined)
+        cipher.setAAD(Buffer.from(aad, 'utf8'));
     const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
     const tag = cipher.getAuthTag();
-    return PREFIX + Buffer.concat([iv, tag, ciphertext]).toString('base64');
+    const prefix = aad === undefined ? PREFIX_V1 : PREFIX_V2;
+    return prefix + Buffer.concat([iv, tag, ciphertext]).toString('base64');
 }
-export function decryptSecret(envelope, key) {
+/** `aad` is ignored for an `enc:v1:` envelope and required for an `enc:v2:` one. */
+export function decryptSecret(envelope, key, aad) {
     if (key.length !== 32) {
         throw new Error(`Secret key must be 32 bytes; got ${key.length}`);
     }
     if (!isEncryptedSecret(envelope)) {
         throw new Error('Value is not an encrypted secret envelope');
     }
-    const buf = Buffer.from(envelope.slice(PREFIX.length), 'base64');
+    const bound = envelope.startsWith(PREFIX_V2);
+    if (bound && aad === undefined) {
+        throw new Error('This secret is bound to a record: pass its id');
+    }
+    const buf = Buffer.from(envelope.slice(PREFIX_V2.length), 'base64');
     const iv = buf.subarray(0, IV_BYTES);
     const tag = buf.subarray(IV_BYTES, IV_BYTES + TAG_BYTES);
     const ciphertext = buf.subarray(IV_BYTES + TAG_BYTES);
     const decipher = createDecipheriv(ALGO, key, iv);
     decipher.setAuthTag(tag);
+    if (bound)
+        decipher.setAAD(Buffer.from(aad, 'utf8'));
     return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
 }
 /**
@@ -55,12 +72,15 @@ export function decryptSecret(envelope, key) {
  * ciphertext nothing can decrypt.
  */
 export function decodeSecretKey(raw) {
-    if (/^[0-9a-fA-F]{64}$/.test(raw))
-        return Buffer.from(raw, 'hex');
-    const buf = Buffer.from(raw, 'base64');
-    if (buf.length === 32)
+    const key = raw.trim();
+    if (/^[0-9a-fA-F]{64}$/.test(key))
+        return Buffer.from(key, 'hex');
+    // `Buffer.from` skips what it can't decode, so only a round trip proves the
+    // whole string was base64 rather than 32 bytes of it.
+    const buf = Buffer.from(key, 'base64');
+    if (buf.length === 32 && buf.toString('base64').replace(/=+$/, '') === key.replace(/=+$/, '')) {
         return buf;
+    }
     throw new Error('SELVA_AT_REST_KEY must be 32 bytes encoded as 64-char hex or base64. ' +
         "Generate one with: node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\"");
 }
-//# sourceMappingURL=secrets.js.map

package/dist/computeServer/types.d.ts

@@ -1,3 +1,7 @@
+export declare const COMPUTE_TIMEOUT_DEFAULT_MS = 30000;
+export declare const COMPUTE_TIMEOUT_MIN_MS = 1000;
+export declare const COMPUTE_TIMEOUT_MAX_MS = 300000;
+export declare const COMPUTE_RETRY_MAX = 5;
 /**
  * Compute servers belong to one of two scopes — never both.
  *
@@ -29,7 +33,7 @@ interface ComputeServerCommon {
      * they'd only throw away.
      */
     hasApiKey?: boolean;
-    /** Default: 30000. */
+    /** Default: {@link COMPUTE_TIMEOUT_DEFAULT_MS}. */
     timeoutMs?: number;
     /** Default: 0. */
     retryCount?: number;
@@ -68,4 +72,3 @@ export interface ComputeConfig {
 export declare function isPlatformServer(s: ComputeServerConfig): s is PlatformComputeServer;
 export declare function isOrgServer(s: ComputeServerConfig): s is OrgComputeServer;
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/computeServer/types.js

@@ -1,3 +1,7 @@
+export const COMPUTE_TIMEOUT_DEFAULT_MS = 30000;
+export const COMPUTE_TIMEOUT_MIN_MS = 1000;
+export const COMPUTE_TIMEOUT_MAX_MS = 300000;
+export const COMPUTE_RETRY_MAX = 5;
 // ============================================================================
 // Type guards
 // ============================================================================
@@ -7,4 +11,3 @@ export function isPlatformServer(s) {
 export function isOrgServer(s) {
     return s.scope === 'org';
 }
-//# sourceMappingURL=types.js.map

package/dist/computeServer/utils.d.ts

@@ -10,18 +10,27 @@ export declare function serversVisibleTo(config: ComputeConfig, orgId: string |
  * default. Returns `undefined` if neither is set or visible.
  */
 export declare function defaultServerIdFor(config: ComputeConfig, orgId: string | null | undefined): string | undefined;
+export interface ResolveOptions {
+    /** Per-definition pin. Falls through silently if not visible. */
+    definitionPin?: string | null;
+}
+/**
+ * From servers already filtered for visibility, the pin if it is among them, then
+ * the default, then the first. Only for a caller holding the filtered list: use
+ * {@link resolveServerForOrg} when you have the config.
+ */
+export declare function pickServer<T extends {
+    id: string;
+}>(visible: readonly T[], defaultId: string | null | undefined, pin: string | null | undefined): T | undefined;
 /**
  * Resolves a definition's compute server, in order:
  *   1. Definition pin (`computeServerId`) if visible to the project's org.
  *   2. `orgDefaults[orgId]` if set.
  *   3. Global `defaultServerId`.
+ *   4. The first visible server, mainly before a default is chosen.
  *
  * Throws if no usable server exists.
  */
-export interface ResolveOptions {
-    /** Per-definition pin. Falls through silently if not visible. */
-    definitionPin?: string | null;
-}
 export declare function resolveServerForOrg(config: ComputeConfig, orgId: string | null | undefined, opts?: ResolveOptions): ComputeServerConfig;
 /**
  * The config as one org may see it: visible servers only, `orgDefaults` reduced
@@ -36,5 +45,7 @@ export declare function scopeConfigToOrg(config: ComputeConfig, orgId: string):
 /** Lookup by id, ignoring scope or visibility — for admin contexts that display a server outside the visibility filter. */
 export declare function findServerById(config: ComputeConfig, id: string): ComputeServerConfig | undefined;
 export declare function platformServers(config: ComputeConfig): import("./types.js").PlatformComputeServer[];
-export declare function orgServersFor(config: ComputeConfig, orgId: string): ComputeServerConfig[];
-//# sourceMappingURL=utils.d.ts.map
+/** What a compute settings form should send for a typed timeout. */
+export declare function clampTimeoutMs(value: unknown): number;
+/** What a compute settings form should send for a typed retry count. */
+export declare function clampRetryCount(value: unknown): number;

package/dist/computeServer/utils.js

@@ -1,4 +1,4 @@
-import { isOrgServer, isPlatformServer } from './types.js';
+import { COMPUTE_RETRY_MAX, COMPUTE_TIMEOUT_DEFAULT_MS, COMPUTE_TIMEOUT_MAX_MS, COMPUTE_TIMEOUT_MIN_MS, isPlatformServer } from './types.js';
 /**
  * Servers an org can see in pickers and use for solves:
  * platform servers shared with this org (or `'all'`, or the global default)
@@ -36,25 +36,30 @@ export function defaultServerIdFor(config, orgId) {
     }
     return undefined;
 }
+/**
+ * From servers already filtered for visibility, the pin if it is among them, then
+ * the default, then the first. Only for a caller holding the filtered list: use
+ * {@link resolveServerForOrg} when you have the config.
+ */
+export function pickServer(visible, defaultId, pin) {
+    // A pin can go stale when an admin un-shares the server, so it falls through.
+    return visible.find((s) => s.id === pin) ?? visible.find((s) => s.id === defaultId) ?? visible[0];
+}
+/**
+ * Resolves a definition's compute server, in order:
+ *   1. Definition pin (`computeServerId`) if visible to the project's org.
+ *   2. `orgDefaults[orgId]` if set.
+ *   3. Global `defaultServerId`.
+ *   4. The first visible server, mainly before a default is chosen.
+ *
+ * Throws if no usable server exists.
+ */
 export function resolveServerForOrg(config, orgId, opts = {}) {
     const visible = serversVisibleTo(config, orgId);
-    if (visible.length === 0) {
+    const server = pickServer(visible, defaultServerIdFor(config, orgId), opts.definitionPin);
+    if (!server)
         throw new Error('No compute servers are configured or visible for this org.');
-    }
-    if (opts.definitionPin) {
-        const pinned = visible.find((s) => s.id === opts.definitionPin);
-        if (pinned)
-            return pinned;
-        // Not visible — admin may have un-shared the server since the pin was set. Fall through.
-    }
-    const defaultId = defaultServerIdFor(config, orgId);
-    if (defaultId) {
-        const found = visible.find((s) => s.id === defaultId);
-        if (found)
-            return found;
-    }
-    // Last resort: first visible server. Mainly hit in tests and initial setup before a default is chosen.
-    return visible[0];
+    return server;
 }
 /**
  * The config as one org may see it: visible servers only, `orgDefaults` reduced
@@ -74,7 +79,7 @@ export function scopeConfigToOrg(config, orgId) {
         defaultServerId: config.defaultServerId && visibleIds.has(config.defaultServerId)
             ? config.defaultServerId
             : undefined,
-        orgDefaults: orgDefault ? { [orgId]: orgDefault } : {}
+        orgDefaults: orgDefault && visibleIds.has(orgDefault) ? { [orgId]: orgDefault } : {}
     };
 }
 /** Lookup by id, ignoring scope or visibility — for admin contexts that display a server outside the visibility filter. */
@@ -87,7 +92,12 @@ export function findServerById(config, id) {
 export function platformServers(config) {
     return config.servers.filter(isPlatformServer);
 }
-export function orgServersFor(config, orgId) {
-    return config.servers.filter((s) => isOrgServer(s) && s.ownerOrgId === orgId);
+/** What a compute settings form should send for a typed timeout. */
+export function clampTimeoutMs(value) {
+    const ms = Number(value) || COMPUTE_TIMEOUT_DEFAULT_MS;
+    return Math.min(COMPUTE_TIMEOUT_MAX_MS, Math.max(COMPUTE_TIMEOUT_MIN_MS, ms));
+}
+/** What a compute settings form should send for a typed retry count. */
+export function clampRetryCount(value) {
+    return Math.min(COMPUTE_RETRY_MAX, Math.max(0, Number(value) || 0));
 }
-//# sourceMappingURL=utils.js.map

package/dist/config.d.ts

@@ -60,5 +60,4 @@ export interface SelvaConfig {
 export type SelvaConfigFactory = (env: Record<string, string | undefined>) => SelvaConfig;
 export declare function isFlagEnabled(config: SelvaConfig, flag: keyof SelvaFlags): boolean;
 /** Identity function for type inference and IDE autocomplete. */
-export declare function defineConfig(config: SelvaConfig | SelvaConfigFactory): SelvaConfig | SelvaConfigFactory;
-//# sourceMappingURL=config.d.ts.map
+export declare function defineConfig<T extends SelvaConfig | SelvaConfigFactory>(config: T): T;

package/dist/config.js

@@ -5,4 +5,3 @@ export function isFlagEnabled(config, flag) {
 export function defineConfig(config) {
     return config;
 }
-//# sourceMappingURL=config.js.map

package/dist/context.d.ts

@@ -37,6 +37,7 @@ export interface RequestContext {
     apiScope?: {
         tokenId: string;
         scopes: readonly ApiScope[];
+        expiresAt: string;
     };
     /** Opaque adapter payload — the Supabase adapter passes the user JWT through for RLS; local ignores it. */
     adapterContext?: unknown;
@@ -61,10 +62,20 @@ export declare function isShareContext(ctx: RequestContext): boolean;
  * definition on one channel, never instance authority.
  */
 export declare function assertNotShareContext(ctx: RequestContext, what: string): void;
+/** May `ctx` read `userId`'s platform permissions? Throws `ProviderError(403)` if not. */
+export declare function assertCanReadPermissions(ctx: RequestContext, userId: string): void;
+/** May `ctx` read several users' platform permissions? Throws `ProviderError(403)` if not. */
+export declare function assertCanReadPermissionsBatch(ctx: RequestContext): void;
+/** May `ctx` change platform permissions? Throws `ProviderError(403)` if not. */
+export declare function assertCanManagePermissions(ctx: RequestContext): void;
+/**
+ * For provider authors: may `ctx` read or change `userId`'s profile? Throws
+ * `ProviderError(403)` if not.
+ */
+export declare function assertCanAccessProfile(ctx: RequestContext, userId: string): void;
 /**
  * Returns the org the caller is acting as, or throws `ProviderError(403)`.
  * Centralizes this guard so every store that scopes rows to an acting org fails
  * the same consistent way, instead of leaking `org_id = undefined` into a query.
  */
 export declare function requireActingOrg(ctx: RequestContext): string;
-//# sourceMappingURL=context.d.ts.map

package/dist/context.js

@@ -14,7 +14,7 @@ export const SYSTEM_CONTEXT = {
  * `actingOrgId` returns false unless `instance_admin` or `system`.
  */
 export function hasPermission(ctx, permission) {
-    if (ctx.system)
+    if (ctx.system && !isShareContext(ctx))
         return true;
     if (ctx.platformPermissions.includes('instance_admin'))
         return true;
@@ -41,6 +41,56 @@ export function assertNotShareContext(ctx, what) {
         throw new ProviderError(`Forbidden: a share link cannot ${what}`, 403);
     }
 }
+// For provider authors: `IPlatformPermissionStore` adapters whose backing store is
+// too coarse to enforce this themselves. Reading one row and reading many agree, and
+// read access is not authority: `set` stays `instance_admin`-only.
+/** May `ctx` read `userId`'s platform permissions? Throws `ProviderError(403)` if not. */
+export function assertCanReadPermissions(ctx, userId) {
+    assertNotShareContext(ctx, 'read permissions');
+    if (ctx.system)
+        return;
+    if (ctx.userId === userId)
+        return;
+    if (hasPermission(ctx, 'instance_admin'))
+        return;
+    if (hasPermission(ctx, 'manage_instance_users'))
+        return;
+    throw new ProviderError('Forbidden: cannot read another user’s permissions', 403);
+}
+/** May `ctx` read several users' platform permissions? Throws `ProviderError(403)` if not. */
+export function assertCanReadPermissionsBatch(ctx) {
+    assertNotShareContext(ctx, 'read permissions');
+    if (ctx.system)
+        return;
+    if (hasPermission(ctx, 'instance_admin'))
+        return;
+    if (hasPermission(ctx, 'manage_instance_users'))
+        return;
+    throw new ProviderError('Forbidden: instance admin or manage_instance_users required', 403);
+}
+/** May `ctx` change platform permissions? Throws `ProviderError(403)` if not. */
+export function assertCanManagePermissions(ctx) {
+    assertNotShareContext(ctx, 'manage permissions');
+    if (ctx.system)
+        return;
+    if (hasPermission(ctx, 'instance_admin'))
+        return;
+    throw new ProviderError('Forbidden: instance admin required', 403);
+}
+/**
+ * For provider authors: may `ctx` read or change `userId`'s profile? Throws
+ * `ProviderError(403)` if not.
+ */
+export function assertCanAccessProfile(ctx, userId) {
+    assertNotShareContext(ctx, 'access user profiles');
+    if (ctx.system)
+        return;
+    if (ctx.userId === userId)
+        return;
+    if (hasPermission(ctx, 'instance_admin'))
+        return;
+    throw new ProviderError('Forbidden: cannot access another user’s profile', 403);
+}
 const PLATFORM_PERMISSION_VALUES = new Set(ALL_PLATFORM_PERMISSIONS);
 function isPlatformPermission(p) {
     return PLATFORM_PERMISSION_VALUES.has(p);
@@ -56,4 +106,3 @@ export function requireActingOrg(ctx) {
     }
     return ctx.actingOrgId;
 }
-//# sourceMappingURL=context.js.map

package/dist/data/index.d.ts

@@ -1,3 +1,2 @@
 export type { IDataProvider, SchemaVersionReport, UserErasureOptions } from './interface.js';
 export { ERASED_ACTOR_ID } from './interface.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/data/index.js

@@ -1,2 +1 @@
 export { ERASED_ACTOR_ID } from './interface.js';
-//# sourceMappingURL=index.js.map

package/dist/data/interface.d.ts

@@ -117,4 +117,3 @@ export interface IDataProvider {
      */
     onUserDeleted(ctx: RequestContext, userId: string, opts?: UserErasureOptions): Promise<void>;
 }
-//# sourceMappingURL=interface.d.ts.map

package/dist/data/interface.js

@@ -15,4 +15,3 @@
  * which marks solves never attributed to a user (share-link / server flows).
  */
 export const ERASED_ACTOR_ID = 'deleted';
-//# sourceMappingURL=interface.js.map

package/dist/definitions/index.d.ts

@@ -2,8 +2,7 @@ export type { DefinitionFileExt, DefinitionListItem, DefinitionRecord, Definitio
 export { toDefinitionListItem } from './types.js';
 export type { IDefinitionStore } from './interface.js';
 export type { UISchema } from '@selvajs/schemas';
-export { GH_EXTENSIONS, COVER_IMAGE_EXTENSIONS, ALLOWED_UPLOAD_EXTENSIONS, COVER_IMAGE_CONTENT_TYPES } from './types.js';
+export { GH_EXTENSIONS, COVER_IMAGE_CONTENT_TYPES } from './types.js';
 export { definitionPaths } from './paths.js';
 export type { UpdateMetadataInput } from './schemas.js';
-export { DefinitionChannelSchema, PublishVersionInputSchema, CreateDefinitionInputSchema, UpdateMetadataInputSchema, GuidSchema, UUID_REGEX } from './schemas.js';
-//# sourceMappingURL=index.d.ts.map
+export { PublishVersionInputSchema, CreateDefinitionInputSchema, UpdateMetadataInputSchema, GuidSchema, toSourceDocumentId } from './schemas.js';

package/dist/definitions/index.js

@@ -1,5 +1,4 @@
 export { toDefinitionListItem } from './types.js';
-export { GH_EXTENSIONS, COVER_IMAGE_EXTENSIONS, ALLOWED_UPLOAD_EXTENSIONS, COVER_IMAGE_CONTENT_TYPES } from './types.js';
+export { GH_EXTENSIONS, COVER_IMAGE_CONTENT_TYPES } from './types.js';
 export { definitionPaths } from './paths.js';
-export { DefinitionChannelSchema, PublishVersionInputSchema, CreateDefinitionInputSchema, UpdateMetadataInputSchema, GuidSchema, UUID_REGEX } from './schemas.js';
-//# sourceMappingURL=index.js.map
+export { PublishVersionInputSchema, CreateDefinitionInputSchema, UpdateMetadataInputSchema, GuidSchema, toSourceDocumentId } from './schemas.js';

package/dist/definitions/interface.d.ts

@@ -75,4 +75,3 @@ export interface IDefinitionStore {
      */
     attachInitialVersion(ctx: RequestContext, definitionId: string, versionId: string): Promise<void>;
 }
-//# sourceMappingURL=interface.d.ts.map

package/dist/definitions/interface.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=interface.js.map

package/dist/definitions/paths.d.ts

@@ -4,4 +4,3 @@ export declare const definitionPaths: {
     readonly image: (guid: string) => string;
     readonly prefix: (guid: string) => string;
 };
-//# sourceMappingURL=paths.d.ts.map

package/dist/definitions/paths.js

@@ -1,14 +1,4 @@
-/**
- * Path-segment safety check. Blocks traversal, separators, NUL, and empty
- * segments. Allowed alphabet `[A-Za-z0-9._-]+` covers GUIDs and sanitized
- * refs. Called by every helper so a malicious `guid` can't escape the
- * `definitions/` prefix.
- */
-function assertSafeKey(value, label) {
-    if (!value || !/^[A-Za-z0-9._-]+$/.test(value) || value === '.' || value === '..') {
-        throw new Error(`Unsafe ${label}: ${JSON.stringify(value)}`);
-    }
-}
+import { assertSafeKey } from '../storage/safeKey.js';
 export const definitionPaths = {
     version: (guid, versionNumber, ext) => {
         assertSafeKey(guid, 'guid');
@@ -26,4 +16,3 @@ export const definitionPaths = {
         return `definitions/${guid}/`;
     }
 };
-//# sourceMappingURL=paths.js.map

package/dist/definitions/schemas.d.ts

@@ -1,31 +1,13 @@
 import { z } from 'zod';
 export declare const UUID_REGEX: RegExp;
 export declare const GuidSchema: z.ZodString;
+/** A Grasshopper document GUID as stores keep and compare it (lowercase), or null for anything else. */
+export declare function toSourceDocumentId(value: unknown): string | null;
 export declare const DefinitionStatusSchema: z.ZodEnum<{
     draft: "draft";
     published: "published";
     archived: "archived";
 }>;
-export declare const DefinitionFileExtSchema: z.ZodEnum<{
-    gh: "gh";
-    ghx: "ghx";
-}>;
-export declare const DefinitionVersionSchema: z.ZodObject<{
-    id: z.ZodString;
-    definitionId: z.ZodString;
-    versionNumber: z.ZodNumber;
-    fileExt: z.ZodEnum<{
-        gh: "gh";
-        ghx: "ghx";
-    }>;
-    fileKey: z.ZodString;
-    originalFilename: z.ZodOptional<z.ZodString>;
-    uploadedBy: z.ZodString;
-    uploadedAt: z.ZodString;
-    changeNote: z.ZodOptional<z.ZodString>;
-    schema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    schemaExtractedAt: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
 export declare const DefinitionChannelSchema: z.ZodEnum<{
     draft: "draft";
     live: "live";
@@ -66,4 +48,3 @@ export type UpdateMetadataInput = z.infer<typeof UpdateMetadataInputSchema>;
 export declare const PublishVersionInputSchema: z.ZodDefault<z.ZodObject<{
     versionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
-//# sourceMappingURL=schemas.d.ts.map

package/dist/definitions/schemas.js

@@ -4,30 +4,22 @@ export const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9
 // regex is what keeps `__proto__` and `constructor` out of a key position.
 // Relaxing it to a looser string re-opens prototype pollution in every store
 // that does `config.definitions[guid]`.
-export const GuidSchema = z.string().regex(UUID_REGEX, 'Invalid GUID format');
+//
+// Lowercases because local keys by raw string while Postgres compares `uuid`
+// columns case-insensitively, so one GUID in two cases is two records on local.
+export const GuidSchema = z.string().toLowerCase().regex(UUID_REGEX, 'Invalid GUID format');
+/** A Grasshopper document GUID as stores keep and compare it (lowercase), or null for anything else. */
+export function toSourceDocumentId(value) {
+    return typeof value === 'string' && UUID_REGEX.test(value) ? value.toLowerCase() : null;
+}
 // Intentionally omits `pending` (see `DefinitionStatus` in ./types.ts): it's a
 // create-internal state `DefinitionService.create` writes during the
 // metadata-first window, and a client must never hand-set it through an update.
 export const DefinitionStatusSchema = z.enum(['draft', 'published', 'archived']);
-export const DefinitionFileExtSchema = z.enum(['gh', 'ghx']);
-export const DefinitionVersionSchema = z.object({
-    id: GuidSchema,
-    definitionId: GuidSchema,
-    versionNumber: z.number().int().min(1),
-    fileExt: DefinitionFileExtSchema,
-    fileKey: z.string().min(1),
-    originalFilename: z.string().max(256).optional(),
-    uploadedBy: z.string().min(1),
-    uploadedAt: z.string(),
-    changeNote: z.string().max(1000).optional(),
-    // Rhino.Compute validates structural correctness at upload; this only asserts it's an object.
-    schema: z.record(z.string(), z.unknown()).optional(),
-    schemaExtractedAt: z.string().optional()
-});
 export const DefinitionChannelSchema = z.enum(['live', 'draft']);
 /** HTTP-body validator for new-definition input. */
 export const CreateDefinitionInputSchema = z.object({
-    displayName: z.string().min(1, 'Display name is required').max(256),
+    displayName: z.string().trim().min(1, 'Display name is required').max(256),
     description: z.string().max(2000).optional(),
     coverImage: z.string().max(2048).optional(),
     category: z.string().max(128).optional(),
@@ -42,7 +34,7 @@ export const CreateDefinitionInputSchema = z.object({
  * - value — set
  */
 export const UpdateMetadataInputSchema = z.object({
-    displayName: z.string().min(1, 'Display name is required').max(256).optional(),
+    displayName: z.string().trim().min(1, 'Display name is required').max(256).optional(),
     description: z.string().max(2000).nullable().optional(),
     coverImage: z.string().max(2048).nullable().optional(),
     category: z.string().max(128).nullable().optional(),
@@ -60,4 +52,3 @@ export const PublishVersionInputSchema = z
     versionId: GuidSchema.optional()
 })
     .default({});
-//# sourceMappingURL=schemas.js.map

package/dist/definitions/types.d.ts

@@ -1,8 +1,8 @@
 import type { UISchema } from '@selvajs/schemas';
+import type { z } from 'zod';
+import type { DefinitionChannelSchema } from './schemas.js';
 export type DefinitionFileExt = 'gh' | 'ghx';
 export declare const GH_EXTENSIONS: string[];
-export declare const COVER_IMAGE_EXTENSIONS: string[];
-export declare const ALLOWED_UPLOAD_EXTENSIONS: string[];
 export declare const COVER_IMAGE_CONTENT_TYPES: Record<string, string>;
 /**
  * - `pending` — internal: metadata written, blob upload may be in flight.
@@ -81,6 +81,12 @@ export interface DefinitionRecord {
      */
     liveVersionId: string | null;
     draftVersionId: string | null;
+    /**
+     * The Grasshopper document GUID (lowercase) from the schema Compute
+     * extracted at the last upload that carried one. A copied `.gh` keeps its
+     * GUID, so this suggests a match and never proves one.
+     */
+    sourceDocumentId?: string;
     createdAt: string;
     updatedAt: string;
     /** Soft-delete marker, independent of `status`: a store filters this out regardless of `archived`. */
@@ -107,6 +113,8 @@ export interface DefinitionListItem {
     status: DefinitionStatus;
     solveCount: number;
     liveVersionId: string | null;
+    /** See {@link DefinitionRecord.sourceDocumentId}. */
+    sourceDocumentId: string | null;
     updatedAt: string;
 }
 export declare function toDefinitionListItem(r: DefinitionRecord): DefinitionListItem;
@@ -132,6 +140,6 @@ export interface DefinitionRecordPatch {
     solveCacheLimit?: number | null;
     status?: DefinitionStatus;
     ownerId?: string;
+    sourceDocumentId?: string | null;
 }
-export type DefinitionChannel = 'live' | 'draft';
-//# sourceMappingURL=types.d.ts.map
+export type DefinitionChannel = z.infer<typeof DefinitionChannelSchema>;

package/dist/definitions/types.js

@@ -1,6 +1,4 @@
 export const GH_EXTENSIONS = ['.gh', '.ghx'];
-export const COVER_IMAGE_EXTENSIONS = ['.jpg', '.jpeg', '.png', '.webp', '.gif'];
-export const ALLOWED_UPLOAD_EXTENSIONS = [...GH_EXTENSIONS, ...COVER_IMAGE_EXTENSIONS];
 export const COVER_IMAGE_CONTENT_TYPES = {
     '.jpg': 'image/jpeg',
     '.jpeg': 'image/jpeg',
@@ -20,7 +18,7 @@ export function toDefinitionListItem(r) {
         status: r.status,
         solveCount: r.solveCount,
         liveVersionId: r.liveVersionId,
+        sourceDocumentId: r.sourceDocumentId ?? null,
         updatedAt: r.updatedAt
     };
 }
-//# sourceMappingURL=types.js.map

package/dist/errors/interface.d.ts

@@ -2,7 +2,7 @@
  * Structured context attached to a reported error. All fields optional — a
  * report can fire before any request context is built (e.g. an
  * `unhandledRejection` with no active request). Deliberately NOT a
- * `RequestContext`: reporters must never receive the opaque `authToken`, so
+ * `RequestContext`: reporters must never receive the opaque `adapterContext`, so
  * only non-sensitive routing/identity fields are surfaced here.
  */
 export interface ErrorContext {
@@ -37,4 +37,3 @@ export interface IErrorReporter {
 export declare class NoopErrorReporter implements IErrorReporter {
     capture(_error: unknown, _context?: ErrorContext): void;
 }
-//# sourceMappingURL=interface.d.ts.map

package/dist/errors/interface.js

@@ -6,4 +6,3 @@
 export class NoopErrorReporter {
     capture(_error, _context) { }
 }
-//# sourceMappingURL=interface.js.map

package/dist/errors.d.ts

@@ -2,8 +2,15 @@
  * Thrown by providers to signal an expected failure the API layer forwards with
  * a specific status. Unknown errors should propagate as plain `Error` and become 500s.
  */
+declare const BRAND: unique symbol;
 export declare class ProviderError extends Error {
     readonly statusCode: number;
+    readonly [BRAND] = true;
+    /**
+     * Providers depend on this package, so a version mismatch installs two copies
+     * and plain `instanceof` would turn a 403 from one into a 500 in the other.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
     constructor(message: string, statusCode?: number);
 }
-//# sourceMappingURL=errors.d.ts.map
+export {};