@streetjs/storage 1.0.0

package/dist/access.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @streetjs/storage — provider-agnostic access control.
+ *
+ * The {@link AccessController} resolves an {@link AccessLevel} decision for a
+ * single object operation (read / write / delete) and, when the caller lacks
+ * the required access, denies the operation with an {@link AuthorizationError}
+ * so no persistence or read is performed. The facade constructs one controller
+ * per {@link Storage} instance and consults it as the first step of the object
+ * operations it guards (see the `put`/`get` data flow in the design).
+ *
+ * Access decisions are delegated to the optional **structural** auth bridge
+ * {@link AuthLike} carried on `config.auth`. This keeps the package free of any
+ * hard dependency on `@streetjs/auth`: any object exposing a compatible
+ * `can(context)` method satisfies the contract (Requirements 11.2, 17.2).
+ *
+ * The controller supports every {@link AccessLevel} value — `public`,
+ * `private`, `signed`, `authenticated`, `role-based`, and `tenant-aware`
+ * (Requirement 11.1) — and applies a single, uniform rule:
+ *
+ *   - **No auth bridge configured** → every operation is permitted. The
+ *     framework stays permissive by default so drivers that never configure
+ *     access control (the in-memory / local defaults) behave exactly as before.
+ *   - **Auth bridge configured** → the bridge's `can(context)` decision governs
+ *     the operation. A `false` decision denies with an {@link AuthorizationError}
+ *     (Requirement 11.3); any other result permits. This is where the
+ *     `authenticated`, `role-based`, and `tenant-aware` levels are resolved
+ *     against StreetJS authentication (Requirement 11.2).
+ *   - **`public` reads** are permitted without authentication; a configured
+ *     bridge may still block them by returning `false`, honoring the "unless
+ *     another configured factor blocks the access" clause (Requirement 11.4).
+ *
+ * _Requirements: 11.1, 11.2, 11.3, 11.4_
+ */
+import type { AccessLevel, AuthLike } from "./types.js";
+export type { AuthLike } from "./types.js";
+/** The class of object operation an access decision governs. */
+export type AccessOperation = "read" | "write" | "delete";
+/**
+ * The subject of a single access decision: the object `key`, the attempted
+ * `operation`, the governing `accessLevel`, and the optional ownership /
+ * tenancy attributes the auth bridge may key its decision on.
+ */
+export interface AccessContext {
+    readonly key: string;
+    readonly operation: AccessOperation;
+    readonly accessLevel: AccessLevel;
+    readonly owner?: string;
+    readonly tenant?: string;
+}
+/** Options for constructing an {@link AccessController}. */
+export interface AccessControllerOptions {
+    /** The optional structural auth bridge that governs access decisions. */
+    readonly auth?: AuthLike;
+}
+/**
+ * Resolves per-object {@link AccessLevel} decisions, denying disallowed
+ * operations with an {@link AuthorizationError}.
+ *
+ * Construct one from `config.auth`; the facade does this once per `Storage`
+ * instance and calls {@link AccessController.authorize} before delegating a
+ * guarded operation to the driver. When no auth bridge is configured the
+ * controller is a permissive no-op, preserving the framework's default
+ * behavior for unconfigured drivers.
+ */
+export declare class AccessController {
+    /** The optional structural auth bridge consulted for every decision. */
+    private readonly auth?;
+    constructor(options?: AccessControllerOptions);
+    /**
+     * Whether access control is actively enforced. This is `true` only when an
+     * auth bridge is configured; callers use it to skip any preparatory work
+     * (e.g. a metadata lookup to discover an object's access level) on the common
+     * unconfigured path so behavior and cost are unchanged when no bridge exists.
+     */
+    get enforced(): boolean;
+    /**
+     * Decide whether `context` is permitted and throw an {@link AuthorizationError}
+     * when it is not (Requirement 11.3). On permit this resolves without a value
+     * and the caller proceeds; on deny it throws before any persistence or read
+     * occurs so the guarded operation has no effect.
+     *
+     * Decision rules:
+     *  - No auth bridge configured → permit (the framework is permissive by
+     *    default so unconfigured drivers are unaffected).
+     *  - `public` reads → permit unless the configured bridge explicitly returns
+     *    `false`, in which case that "other configured factor" blocks the access
+     *    (Requirement 11.4).
+     *  - Otherwise → the bridge's `can(context)` decision governs; a `false`
+     *    result denies, any other result permits (Requirements 11.1, 11.2).
+     */
+    authorize(context: AccessContext): Promise<void>;
+    /** Build the descriptive {@link AuthorizationError} for a denied context. */
+    private denial;
+}
+//# sourceMappingURL=access.d.ts.map

package/dist/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAMxD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B;AAKD;;;;;;;;;GASG;AACH,qBAAa,gBAAgB;IAC3B,wEAAwE;IACxE,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAW;gBAErB,OAAO,GAAE,uBAA4B;IAIjD;;;;;OAKG;IACH,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED;;;;;;;;;;;;;;OAcG;IACG,SAAS,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IA+BtD,6EAA6E;IAC7E,OAAO,CAAC,MAAM;CAWf"}

package/dist/access.js

@@ -0,0 +1,114 @@
+/**
+ * @streetjs/storage — provider-agnostic access control.
+ *
+ * The {@link AccessController} resolves an {@link AccessLevel} decision for a
+ * single object operation (read / write / delete) and, when the caller lacks
+ * the required access, denies the operation with an {@link AuthorizationError}
+ * so no persistence or read is performed. The facade constructs one controller
+ * per {@link Storage} instance and consults it as the first step of the object
+ * operations it guards (see the `put`/`get` data flow in the design).
+ *
+ * Access decisions are delegated to the optional **structural** auth bridge
+ * {@link AuthLike} carried on `config.auth`. This keeps the package free of any
+ * hard dependency on `@streetjs/auth`: any object exposing a compatible
+ * `can(context)` method satisfies the contract (Requirements 11.2, 17.2).
+ *
+ * The controller supports every {@link AccessLevel} value — `public`,
+ * `private`, `signed`, `authenticated`, `role-based`, and `tenant-aware`
+ * (Requirement 11.1) — and applies a single, uniform rule:
+ *
+ *   - **No auth bridge configured** → every operation is permitted. The
+ *     framework stays permissive by default so drivers that never configure
+ *     access control (the in-memory / local defaults) behave exactly as before.
+ *   - **Auth bridge configured** → the bridge's `can(context)` decision governs
+ *     the operation. A `false` decision denies with an {@link AuthorizationError}
+ *     (Requirement 11.3); any other result permits. This is where the
+ *     `authenticated`, `role-based`, and `tenant-aware` levels are resolved
+ *     against StreetJS authentication (Requirement 11.2).
+ *   - **`public` reads** are permitted without authentication; a configured
+ *     bridge may still block them by returning `false`, honoring the "unless
+ *     another configured factor blocks the access" clause (Requirement 11.4).
+ *
+ * _Requirements: 11.1, 11.2, 11.3, 11.4_
+ */
+import { AuthorizationError } from "./errors.js";
+/** Read-like operations that a `public` access level permits without auth. */
+const READ_OPERATIONS = new Set(["read"]);
+/**
+ * Resolves per-object {@link AccessLevel} decisions, denying disallowed
+ * operations with an {@link AuthorizationError}.
+ *
+ * Construct one from `config.auth`; the facade does this once per `Storage`
+ * instance and calls {@link AccessController.authorize} before delegating a
+ * guarded operation to the driver. When no auth bridge is configured the
+ * controller is a permissive no-op, preserving the framework's default
+ * behavior for unconfigured drivers.
+ */
+export class AccessController {
+    /** The optional structural auth bridge consulted for every decision. */
+    auth;
+    constructor(options = {}) {
+        this.auth = options.auth;
+    }
+    /**
+     * Whether access control is actively enforced. This is `true` only when an
+     * auth bridge is configured; callers use it to skip any preparatory work
+     * (e.g. a metadata lookup to discover an object's access level) on the common
+     * unconfigured path so behavior and cost are unchanged when no bridge exists.
+     */
+    get enforced() {
+        return this.auth !== undefined;
+    }
+    /**
+     * Decide whether `context` is permitted and throw an {@link AuthorizationError}
+     * when it is not (Requirement 11.3). On permit this resolves without a value
+     * and the caller proceeds; on deny it throws before any persistence or read
+     * occurs so the guarded operation has no effect.
+     *
+     * Decision rules:
+     *  - No auth bridge configured → permit (the framework is permissive by
+     *    default so unconfigured drivers are unaffected).
+     *  - `public` reads → permit unless the configured bridge explicitly returns
+     *    `false`, in which case that "other configured factor" blocks the access
+     *    (Requirement 11.4).
+     *  - Otherwise → the bridge's `can(context)` decision governs; a `false`
+     *    result denies, any other result permits (Requirements 11.1, 11.2).
+     */
+    async authorize(context) {
+        // Permissive default: with no configured auth bridge nothing is denied, so
+        // drivers that never configure access control behave exactly as before.
+        if (this.auth === undefined) {
+            return;
+        }
+        const decision = await this.auth.can({
+            key: context.key,
+            operation: context.operation,
+            accessLevel: context.accessLevel,
+            owner: context.owner,
+            tenant: context.tenant,
+        });
+        // A `public` read is permitted without authentication; a bridge may still
+        // block it, but only by explicitly returning `false` (Requirement 11.4).
+        if (context.accessLevel === "public" && READ_OPERATIONS.has(context.operation)) {
+            if (decision === false) {
+                throw this.denial(context);
+            }
+            return;
+        }
+        // For every other level/operation the bridge's decision is authoritative:
+        // a `false` result denies the operation (Requirement 11.3).
+        if (decision === false) {
+            throw this.denial(context);
+        }
+    }
+    /** Build the descriptive {@link AuthorizationError} for a denied context. */
+    denial(context) {
+        return new AuthorizationError(`Access denied: operation "${context.operation}" on "${context.key}" ` +
+            `is not permitted for access level "${context.accessLevel}".`, {
+            key: context.key,
+            operation: context.operation,
+            accessLevel: context.accessLevel,
+        });
+    }
+}
+//# sourceMappingURL=access.js.map

package/dist/access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.js","sourceRoot":"","sources":["../src/access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA+BjD,8EAA8E;AAC9E,MAAM,eAAe,GAAiC,IAAI,GAAG,CAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,OAAO,gBAAgB;IAC3B,wEAAwE;IACvD,IAAI,CAAY;IAEjC,YAAY,UAAmC,EAAE;QAC/C,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,SAAS,CAAC,OAAsB;QACpC,2EAA2E;QAC3E,wEAAwE;QACxE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YACnC,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,MAAM,EAAE,OAAO,CAAC,MAAM;SACvB,CAAC,CAAC;QAEH,0EAA0E;QAC1E,yEAAyE;QACzE,IAAI,OAAO,CAAC,WAAW,KAAK,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC/E,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;gBACvB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7B,CAAC;YACD,OAAO;QACT,CAAC;QAED,0EAA0E;QAC1E,4DAA4D;QAC5D,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YACvB,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,6EAA6E;IACrE,MAAM,CAAC,OAAsB;QACnC,OAAO,IAAI,kBAAkB,CAC3B,6BAA6B,OAAO,CAAC,SAAS,SAAS,OAAO,CAAC,GAAG,IAAI;YACpE,sCAAsC,OAAO,CAAC,WAAW,IAAI,EAC/D;YACE,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CACF,CAAC;IACJ,CAAC;CACF"}

package/dist/cli/commands.d.ts

@@ -0,0 +1,88 @@
+import type { ParsedArgs } from "streetjs";
+/**
+ * The set of `@Command`-decorated storage commands, registered through the core
+ * `CliKernel`. A plain class (no class-level decorator) so the kernel can
+ * `container.resolve` it without constructor dependency metadata.
+ */
+export declare class StorageCommands {
+    /**
+     * `street make:storage <Name> [--dir <dir>] [--provider memory|local]` —
+     * scaffold a typed storage module. Delegates to the pure generators: the name
+     * (and scaffold provider) are validated before any file is written, and an
+     * existing target is never overwritten (Requirement 21.2).
+     */
+    makeStorage(args: ParsedArgs): void;
+    /**
+     * `street storage:list [<prefix>] [--provider memory|local] [--root <dir>]` —
+     * list the stored object keys for the configured driver. Builds a `Storage`
+     * from the CLI flags and prints every key under the prefix (Requirement 21.3).
+     */
+    storageList(args: ParsedArgs): Promise<void>;
+    /**
+     * `street storage:clean <prefix> [--provider memory|local] [--root <dir>]` —
+     * remove every object under a prefix from the configured driver. A prefix is
+     * required so the command never silently wipes an entire store; deletion of
+     * each object is isolated so one failure does not abort the rest
+     * (Requirement 21.3).
+     */
+    storageClean(args: ParsedArgs): Promise<void>;
+    /**
+     * `street storage:sync [<prefix>] --from-provider <p> [--from-root <dir>]
+     * --to-provider <p> [--to-root <dir>]` — copy every object under a prefix from
+     * a source store to a destination store, leaving the source untouched
+     * (Requirement 21.3). Each object copy is isolated so a single failure does
+     * not abort the whole sync.
+     */
+    storageSync(args: ParsedArgs): Promise<void>;
+    /**
+     * `street storage:migrate [<prefix>] --from-provider <p> [--from-root <dir>]
+     * --to-provider <p> [--to-root <dir>]` — move every object under a prefix from
+     * a source store to a destination store (copy, then remove from the source),
+     * so the destination becomes the new home for the data (Requirement 21.3).
+     * Each object migration is isolated so a single failure does not abort the
+     * whole migration.
+     */
+    storageMigrate(args: ParsedArgs): Promise<void>;
+    /**
+     * `street storage:verify [--provider memory|local] [--root <dir>]` — run the
+     * shared driver contract-conformance suite against the configured driver and
+     * report pass/fail per check, exiting non-zero when any check fails
+     * (Requirement 21.4).
+     */
+    storageVerify(args: ParsedArgs): Promise<void>;
+    /**
+     * Copy (and optionally remove-from-source) every object under a prefix from a
+     * source store to a destination store. Shared by `storage:sync` (copy) and
+     * `storage:migrate` (move). Every per-object transfer is isolated so one
+     * failure does not abort the rest.
+     */
+    private transfer;
+    /** Build a live {@link Storage} facade from a resolved {@link StorageConfig}. */
+    private buildStorage;
+    /**
+     * Resolve a {@link StorageConfig} from the CLI flags: `--provider` (defaults to
+     * `memory`) and `--root` (used by the `local` provider).
+     */
+    private configFromArgs;
+    /**
+     * Resolve a source (`from`) or destination (`to`) {@link StorageConfig} from a
+     * prefixed pair of flags, e.g. `--from-provider`/`--from-root` and
+     * `--to-provider`/`--to-root`. Defaults to the `memory` provider.
+     */
+    private transferConfig;
+    /**
+     * Build a {@link StorageDriverFactory} for the configured driver, used by
+     * `storage:verify` to obtain a freshly constructed driver per contract check.
+     * A pre-constructed `config.driver` is returned as-is; the built-in `memory`
+     * and `local` providers are constructed fresh each call. An unknown provider
+     * with no supplied driver throws a descriptive {@link StorageConfigError}.
+     */
+    private driverFactory;
+    /** Read the generator name from the first positional arg or `--name`. */
+    private resolveName;
+    /** Read the key prefix from the first positional arg or `--prefix` (default ""). */
+    private resolvePrefix;
+    /** Close a storage facade, swallowing any error so cleanup never masks results. */
+    private closeQuietly;
+}
+//# sourceMappingURL=commands.d.ts.map

package/dist/cli/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAoB3C;;;;GAIG;AACH,qBAAa,eAAe;IAG1B;;;;;OAKG;IAKH,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IA0CnC;;;;OAIG;IAKG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlD;;;;;;OAMG;IAKG,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCnD;;;;;;OAMG;IAKG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlD;;;;;;;OAOG;IAKG,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD;;;;;OAKG;IAKG,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgCpD;;;;;OAKG;YACW,QAAQ;IA6CtB,iFAAiF;IACjF,OAAO,CAAC,YAAY;IAIpB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAOtB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAQtB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAyBrB,yEAAyE;IACzE,OAAO,CAAC,WAAW;IAQnB,oFAAoF;IACpF,OAAO,CAAC,aAAa;IAQrB,mFAAmF;YACrE,YAAY;CAO3B"}