@sequenceholdings/storage 0.1.0

package/dist/contracts.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageErrorSchema = exports.storageAccessSchema = exports.updateStorageAccessSchema = exports.storagePrincipalSchema = exports.uploadSessionSchema = exports.completeUploadSchema = exports.startUploadSchema = exports.storageChecksum = exports.updateNodeSchema = exports.createFolderSchema = exports.listStorageSchema = exports.storagePage = exports.listStorageOperationsSchema = exports.storageOperationScope = exports.operationSchema = exports.versionSchema = exports.nodeSchema = exports.workspaceSchema = exports.workspaceManifestSchema = exports.storageMetadata = exports.storagePath = exports.storageName = exports.storageLifecycle = exports.storageRole = exports.storageId = void 0;
+const zod_1 = require("zod");
+const paths_js_1 = require("./paths.js");
+exports.storageId = zod_1.z.uuid();
+exports.storageRole = zod_1.z.enum(['viewer', 'editor', 'admin', 'owner']);
+exports.storageLifecycle = zod_1.z.enum(['active', 'trashed', 'purging']);
+exports.storageName = zod_1.z.string().transform((value, ctx) => {
+    try {
+        return (0, paths_js_1.normalizeStorageName)(value);
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: 'custom',
+            message: error instanceof Error ? error.message : 'Invalid name',
+        });
+        return zod_1.z.NEVER;
+    }
+});
+exports.storagePath = zod_1.z.string().transform((value, ctx) => {
+    try {
+        return (0, paths_js_1.splitStoragePath)(value).join('/');
+    }
+    catch (error) {
+        ctx.addIssue({
+            code: 'custom',
+            message: error instanceof Error ? error.message : 'Invalid path',
+        });
+        return zod_1.z.NEVER;
+    }
+});
+exports.storageMetadata = zod_1.z
+    .record(zod_1.z.string().max(64), zod_1.z.string().max(1024))
+    .refine((value) => Object.keys(value).length <= 32, 'At most 32 metadata fields');
+exports.workspaceManifestSchema = zod_1.z.strictObject({
+    workspace: zod_1.z.strictObject({
+        name: zod_1.z.string().regex(/^[a-z][a-z0-9-]{1,62}$/),
+        description: zod_1.z.string().max(2000).default(''),
+    }),
+});
+exports.workspaceSchema = zod_1.z.object({
+    id: exports.storageId,
+    name: zod_1.z.string(),
+    description: zod_1.z.string(),
+    environment: zod_1.z.string(),
+    state: exports.storageLifecycle,
+    revision: zod_1.z.number().int(),
+    createdAt: zod_1.z.string(),
+    role: exports.storageRole,
+    quotaBytes: zod_1.z.number(),
+    usedBytes: zod_1.z.number(),
+    reservedBytes: zod_1.z.number(),
+});
+exports.nodeSchema = zod_1.z.object({
+    id: exports.storageId,
+    workspaceId: exports.storageId,
+    parentId: exports.storageId.nullable(),
+    name: zod_1.z.string(),
+    kind: zod_1.z.enum(['folder', 'file']),
+    state: exports.storageLifecycle,
+    restricted: zod_1.z.boolean(),
+    revision: zod_1.z.number().int(),
+    currentVersionId: exports.storageId.nullable(),
+    metadata: exports.storageMetadata,
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+    role: exports.storageRole.exclude(['owner']),
+    size: zod_1.z.number().nullable(),
+    contentType: zod_1.z.string().nullable(),
+});
+exports.versionSchema = zod_1.z.object({
+    id: exports.storageId,
+    fileId: exports.storageId,
+    revision: zod_1.z.number().int(),
+    size: zod_1.z.number(),
+    checksum: zod_1.z.string(),
+    contentType: zod_1.z.string(),
+    createdAt: zod_1.z.string(),
+    createdBy: zod_1.z.string(),
+    state: zod_1.z.enum(['active', 'purging']),
+});
+exports.operationSchema = zod_1.z.object({
+    id: exports.storageId,
+    workspaceId: exports.storageId,
+    targetId: exports.storageId.nullable(),
+    kind: zod_1.z.enum(['purge', 'delete_version']),
+    status: zod_1.z.enum(['queued', 'running', 'succeeded', 'failed']),
+    completed: zod_1.z.number().int(),
+    total: zod_1.z.number().int(),
+    error: zod_1.z.string().nullable(),
+    createdAt: zod_1.z.string(),
+    updatedAt: zod_1.z.string(),
+    /** The caller may retry once failed: its initiator, the workspace Owner, or a Sequence operator. */
+    canRetry: zod_1.z.boolean(),
+});
+/** `mine` lists the caller's own jobs; `workspace` every job (Admins and Sequence operators). */
+exports.storageOperationScope = zod_1.z.enum(['mine', 'workspace']);
+exports.listStorageOperationsSchema = zod_1.z.object({
+    before: exports.storageId.optional(),
+    limit: zod_1.z.coerce.number().int().min(1).max(100).default(50),
+    scope: exports.storageOperationScope.default('mine'),
+});
+const storagePage = (item) => zod_1.z.object({
+    items: zod_1.z.array(item),
+    nextCursor: zod_1.z.string().nullable(),
+});
+exports.storagePage = storagePage;
+exports.listStorageSchema = zod_1.z.object({
+    limit: zod_1.z.coerce.number().int().min(1).max(100).default(50),
+    cursor: zod_1.z.string().max(2048).optional(),
+    q: zod_1.z.string().max(255).default(''),
+    sort: zod_1.z.enum(['name', 'newest']).default('name'),
+});
+exports.createFolderSchema = zod_1.z.strictObject({
+    parentId: exports.storageId.nullable().default(null),
+    name: exports.storageName,
+    /** A replay by the same principal returns the folder this key created. */
+    idempotencyKey: zod_1.z.string().min(1).max(128).optional(),
+});
+exports.updateNodeSchema = zod_1.z.strictObject({
+    expectedRevision: zod_1.z.number().int().nonnegative(),
+    name: exports.storageName.optional(),
+    parentId: exports.storageId.nullable().optional(),
+    metadata: exports.storageMetadata.optional(),
+});
+/** CRC32C in GCS's encoding: base64 of the big-endian uint32. */
+exports.storageChecksum = zod_1.z.string().regex(/^[A-Za-z0-9+/]{6}==$/);
+exports.startUploadSchema = zod_1.z
+    .strictObject({
+    parentId: exports.storageId.nullable().default(null),
+    path: exports.storagePath,
+    fileId: exports.storageId.optional(),
+    expectedRevision: zod_1.z.number().int().nonnegative().optional(),
+    size: zod_1.z.number().int().nonnegative().safe().optional(),
+    contentType: zod_1.z
+        .string()
+        .max(255)
+        .regex(/^[\w!#$&^.+-]+\/[\w!#$&^.+-]+$/)
+        .default('application/octet-stream'),
+    /** CRC32C the producer knows in advance; completion rejects any other object. */
+    checksum: exports.storageChecksum.optional(),
+    idempotencyKey: zod_1.z.string().min(1).max(128),
+})
+    .refine((v) => Boolean(v.fileId) === (v.expectedRevision !== undefined), {
+    message: 'Replacement requires both fileId and expectedRevision',
+});
+exports.completeUploadSchema = zod_1.z.strictObject({
+    /**
+     * CRC32C the SDK computed over the source it sent, from byte zero. Completion
+     * rejects and aborts the session when the stored object differs. Optional
+     * until every in-repo consumer sends it; then it becomes required.
+     */
+    crc32c: exports.storageChecksum.optional(),
+});
+exports.uploadSessionSchema = zod_1.z.object({
+    id: exports.storageId,
+    fileId: exports.storageId,
+    uploadUrl: zod_1.z.url().nullable(),
+    expiresAt: zod_1.z.string(),
+    state: zod_1.z.enum(['pending', 'complete', 'aborted']),
+    versionId: exports.storageId.nullable(),
+    maxBytes: zod_1.z.number().int(),
+});
+exports.storagePrincipalSchema = zod_1.z.strictObject({
+    type: zod_1.z.enum(['user', 'group', 'organization', 'service_account']),
+    id: zod_1.z.string().min(1).max(255),
+    role: exports.storageRole.exclude(['owner']),
+});
+exports.updateStorageAccessSchema = zod_1.z.strictObject({
+    expectedRevision: zod_1.z.number().int().nonnegative(),
+    restricted: zod_1.z.boolean(),
+    grants: zod_1.z.array(exports.storagePrincipalSchema).max(40),
+});
+exports.storageAccessSchema = zod_1.z.object({
+    revision: zod_1.z.number().int(),
+    restricted: zod_1.z.boolean(),
+    grants: zod_1.z.array(exports.storagePrincipalSchema),
+    owner: zod_1.z.string().nullable(),
+    inherited: zod_1.z.boolean(),
+    workspaceAdminOverride: zod_1.z.literal(true),
+    displayNames: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).default({}),
+});
+exports.storageErrorSchema = zod_1.z.object({
+    error: zod_1.z.object({ code: zod_1.z.string(), message: zod_1.z.string() }),
+});

package/dist/crc32c.d.ts

@@ -0,0 +1,11 @@
+/** Incremental CRC32C: `update` any split of the input, then `digest`. */
+export declare class Crc32c {
+    #private;
+    update(bytes: Uint8Array): this;
+    /** The checksum of everything passed to `update` so far, as a uint32. */
+    value(): number;
+    /** The checksum in GCS's encoding. Does not reset; `update` may continue. */
+    digest(): string;
+}
+/** One-shot CRC32C of `bytes` in GCS's base64 encoding. */
+export declare function crc32c(bytes: Uint8Array): string;

package/dist/crc32c.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Crc32c = void 0;
+exports.crc32c = crc32c;
+/**
+ * CRC32C (Castagnoli), the checksum GCS records for every object. Digests use
+ * GCS's encoding: base64 of the big-endian uint32, as in `x-goog-hash: crc32c=`
+ * and the object resource's `crc32c` field.
+ *
+ * Slicing-by-8 over eight 256-entry tables: one table lookup per input byte,
+ * eight bytes per loop iteration. Pure TypeScript so the SDK runs unchanged in
+ * browsers, Artifact sandboxes and Node without a native dependency.
+ */
+const CASTAGNOLI_REFLECTED = 0x82f63b78;
+function buildTables() {
+    const tables = Array.from({ length: 8 }, () => new Uint32Array(256));
+    const [base] = tables;
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? (c >>> 1) ^ CASTAGNOLI_REFLECTED : c >>> 1;
+        base[n] = c;
+    }
+    for (let n = 0; n < 256; n++) {
+        let c = base[n];
+        for (let k = 1; k < 8; k++) {
+            c = base[c & 0xff] ^ (c >>> 8);
+            tables[k][n] = c;
+        }
+    }
+    return tables;
+}
+const [T0, T1, T2, T3, T4, T5, T6, T7] = buildTables();
+/** Incremental CRC32C: `update` any split of the input, then `digest`. */
+class Crc32c {
+    #crc = 0xffffffff;
+    update(bytes) {
+        let crc = this.#crc;
+        let i = 0;
+        const end8 = bytes.length - (bytes.length % 8);
+        for (; i < end8; i += 8) {
+            const low = crc ^
+                (bytes[i] |
+                    (bytes[i + 1] << 8) |
+                    (bytes[i + 2] << 16) |
+                    (bytes[i + 3] << 24));
+            crc =
+                T7[low & 0xff] ^
+                    T6[(low >>> 8) & 0xff] ^
+                    T5[(low >>> 16) & 0xff] ^
+                    T4[low >>> 24] ^
+                    T3[bytes[i + 4]] ^
+                    T2[bytes[i + 5]] ^
+                    T1[bytes[i + 6]] ^
+                    T0[bytes[i + 7]];
+        }
+        for (; i < bytes.length; i++)
+            crc = T0[(crc ^ bytes[i]) & 0xff] ^ (crc >>> 8);
+        this.#crc = crc;
+        return this;
+    }
+    /** The checksum of everything passed to `update` so far, as a uint32. */
+    value() {
+        return (this.#crc ^ 0xffffffff) >>> 0;
+    }
+    /** The checksum in GCS's encoding. Does not reset; `update` may continue. */
+    digest() {
+        const value = this.value();
+        return btoa(String.fromCharCode(value >>> 24, (value >>> 16) & 0xff, (value >>> 8) & 0xff, value & 0xff));
+    }
+}
+exports.Crc32c = Crc32c;
+/** One-shot CRC32C of `bytes` in GCS's base64 encoding. */
+function crc32c(bytes) {
+    return new Crc32c().update(bytes).digest();
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './contracts.js';
+export * from './paths.js';
+export * from './client.js';
+export * from './transfer.js';
+export * from './crc32c.js';
+export * from './scope.js';

package/dist/index.js

@@ -0,0 +1,22 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./contracts.js"), exports);
+__exportStar(require("./paths.js"), exports);
+__exportStar(require("./client.js"), exports);
+__exportStar(require("./transfer.js"), exports);
+__exportStar(require("./crc32c.js"), exports);
+__exportStar(require("./scope.js"), exports);

package/dist/paths.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_STORAGE_DEPTH = 16;
+/** Case-sensitive, NFC names. Paths never undergo URL decoding or traversal resolution. */
+export declare function normalizeStorageName(name: string): string;
+export declare function splitStoragePath(path: string): string[];

package/dist/paths.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_STORAGE_DEPTH = void 0;
+exports.normalizeStorageName = normalizeStorageName;
+exports.splitStoragePath = splitStoragePath;
+// Leave room for role and group rewrites under OpenFGA’s 25-node resolve limit.
+// The maximum inherited chain is covered by authz/model.fga.yaml.
+exports.MAX_STORAGE_DEPTH = 16;
+/** Case-sensitive, NFC names. Paths never undergo URL decoding or traversal resolution. */
+function normalizeStorageName(name) {
+    const normalized = name.normalize('NFC');
+    if (!normalized ||
+        normalized !== normalized.trim() ||
+        normalized === '.' ||
+        normalized === '..' ||
+        /[\/\\\u0000-\u001f\u007f]/u.test(normalized) ||
+        new TextEncoder().encode(normalized).byteLength > 255)
+        throw new Error('Names must be 1–255 UTF-8 bytes, without separators, control characters, or surrounding whitespace');
+    return normalized;
+}
+function splitStoragePath(path) {
+    const parts = path.split('/');
+    if (parts.length > exports.MAX_STORAGE_DEPTH ||
+        new TextEncoder().encode(path).byteLength > 4096) {
+        throw new Error(`Path exceeds the ${exports.MAX_STORAGE_DEPTH}-level or 4096-byte limit`);
+    }
+    return parts.map(normalizeStorageName);
+}

package/dist/scope.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+/** Maximum consumer reach. This declaration never grants resource permissions. */
+export declare const storageScopesSchema: z.ZodRecord<z.ZodUUID, z.ZodEnum<{
+    viewer: "viewer";
+    editor: "editor";
+    admin: "admin";
+}>>;
+export type StorageScopes = z.infer<typeof storageScopesSchema>;
+export declare function readStorageScopes(manifest: unknown): StorageScopes;
+/** Catalog discovery and workspace provisioning are not delegated to consumers. */
+export declare function storageScopeAllows({ scopes, method, pathname, }: {
+    scopes: StorageScopes;
+    method: string;
+    pathname: string;
+}): boolean;

package/dist/scope.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storageScopesSchema = void 0;
+exports.readStorageScopes = readStorageScopes;
+exports.storageScopeAllows = storageScopeAllows;
+const zod_1 = require("zod");
+/** Maximum consumer reach. This declaration never grants resource permissions. */
+exports.storageScopesSchema = zod_1.z
+    .record(zod_1.z.uuid(), zod_1.z.enum(['viewer', 'editor', 'admin']))
+    .refine((value) => Object.keys(value).length <= 64, 'At most 64 workspace bindings');
+function readStorageScopes(manifest) {
+    const parsed = zod_1.z
+        .object({
+        capabilities: zod_1.z
+            .object({ storage: exports.storageScopesSchema.optional() })
+            .optional(),
+    })
+        .safeParse(manifest);
+    return parsed.success ? (parsed.data.capabilities?.storage ?? {}) : {};
+}
+/** Catalog discovery and workspace provisioning are not delegated to consumers. */
+function storageScopeAllows({ scopes, method, pathname, }) {
+    const match = /^\/api\/storage\/workspaces\/([0-9a-f-]{36})(\/.*)?$/.exec(pathname);
+    if (!match)
+        return false;
+    const role = scopes[match[1]];
+    if (!role)
+        return false;
+    const suffix = match[2] ?? '';
+    const upper = method.toUpperCase();
+    if (suffix === '/owner' || (!suffix && upper !== 'GET'))
+        return false;
+    if (suffix.endsWith('/access'))
+        return role === 'admin';
+    if (suffix.endsWith('/purge') ||
+        (/\/versions\/[0-9a-f-]+$/.test(suffix) && upper === 'DELETE') ||
+        suffix.endsWith('/retry'))
+        return role === 'admin';
+    if (upper === 'GET' || (upper === 'POST' && suffix.endsWith('/download')))
+        return true;
+    return role === 'editor' || role === 'admin';
+}

package/dist/transfer.d.ts

@@ -0,0 +1,34 @@
+export type StorageUploadSource = Blob | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+export interface StorageTransferOptions {
+    signal?: AbortSignal;
+    onProgress?: (uploadedBytes: number) => void;
+    fetch?: typeof fetch;
+    /** Multiples of 256 KiB, between 256 KiB and 32 MiB. Defaults to 8 MiB. */
+    chunkBytes?: number;
+    /** Use one request for a small Blob. Large/streaming inputs remain chunked. */
+    method?: 'simple' | 'resumable';
+}
+export interface StorageTransferResult {
+    /**
+     * CRC32C of the whole source as this call read it from byte zero, in GCS's
+     * encoding. Pass it to upload completion so the server can compare it with
+     * the stored object.
+     */
+    crc32c: string;
+}
+export declare class StorageTransferError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * Resume a session with the original source, starting at byte zero. The
+ * acknowledged prefix is read again (and discarded with bounded memory) so the
+ * returned CRC32C covers the whole object, not just the bytes this call sent.
+ * Session URLs are bearer credentials: never persist them in logs or telemetry.
+ */
+export declare function transferStorageUpload({ uploadUrl, source, size, maxBytes, ...options }: StorageTransferOptions & {
+    uploadUrl: string;
+    source: StorageUploadSource;
+    size?: number;
+    maxBytes: number;
+}): Promise<StorageTransferResult>;