@krizaka/storage

InstallCopy Anchor Link

npm install @krizaka/storage

Also published as subpath exports: @krizaka/storage/node, @krizaka/storage/settings, @krizaka/storage/resolve, @krizaka/storage/testkit, @krizaka/storage/provider-admin, @krizaka/storage/opendal.

Files behind one port for every Krizaka product. The port is named by what it does (ObjectStore), the provider is a value the admin chooses. No vendor SDK (plain HTTP through an injected fetch), no environment variable, no wall clock.

• The port. put, get, head, delete, list(prefix), signedUrl(key, ttl) for a private zone, publicUrl(key) when a pull zone or CDN exists.
• Adapters. remoteStore (an HTTP zone with the shape of Bunny Storage: AccessKey header, PUT/GET/DELETE, a directory listed by its path with a trailing slash, a pull zone with token-signed links), bucketStore (any S3-compatible service: Signature V4, presigned GET, ListObjectsV2, no SDK), folderStore (a folder, for development, tests and the Mac apps; a key never leaves the root), memoryObjectStore. All run objectStoreContract (@krizaka/storage/testkit).
• Rules every upload obeys (createStorage): the size limit is passed in, the prefix must be declared in a defineLayout (an unknown prefix is refused), the bytes are checked by magic number (sniffType: png, jpeg, gif, webp, pdf, mp4, webm, svg), never by the extension, and a declared type that contradicts the bytes is refused. The stored name is content-hashed, <name>.<sha10>.<ext>, so a URL never changes content.
• The admin chooses (@krizaka/storage/settings): storage.provider (local, http, s3), storage.maxMegabytes, storage.signedUrlSeconds, and the non-secret coordinates (endpoint, region, bucket, zone, prefix, pullHostname, publicBaseUrl). Keys stay in the environment; storeFromSettings takes them as parameters and refuses a provider chosen without what it needs, instead of falling back to another. An admin-typed S3 endpoint goes through checkEndpoint (https only, no credentials, no local or private address).
• Encryption at rest, the vault, regions and where. encryptedStore(inner, key) (AES-256-GCM over any ObjectStore; the key is a parameter; the provider holds ciphertext; no link is handed out), seal/open (credentials in the database, v1. envelope), COUNTRY_OF_REGION (the one region table: an unlisted region is never a country; residencyOfConfig says « canada » only when the region and the endpoint agree, never for a Bunny-shaped zone), where(kind, active, { fixed, devOnly }) and storageNotice (the sentence key of the info panel, from the configuration).
• Admin over environment (@krizaka/storage/resolve). resolveStorage(env, admin) serves every kind of data (documents, avatars: pass each its own DeploymentStorage): the admin's storage.* wins, the environment gives the secrets and the fallback when the admin left local. If the environment says none and the admin turns keeping on, it throws StorageError STORAGE_KEEPING_OFF (call it when saving the setting to refuse early): keeping is turned on in the environment, never by a setting alone. openResolved builds the store, encrypted when a key is given.
• Provider registry (ADR-005). PROVIDER_KINDS is the table of kinds as data (bunny, s3 with presets DigitalOcean Spaces, AWS S3, OVHcloud and generic, dropbox, reserved google-drive/onedrive, folder, device): scopes, runtimes, devOnly, capabilities, coordinate and credential field schemas. openProvider(kind, coordinates, credentials, { runtime, environment, fetch, clock }) (/node) is the only factory: it refuses (STORAGE_BAD_CONFIG) devOnly kinds in prod, folder outside dev, an unknown or unimplemented kind and a missing field, and never falls back. It returns the store and a ResidencyLabel (PROVINCE_OF_REGION: « Canada (Québec) », « Canada (Ontario) »…) for the screen to show before saving. testConnection (probe write, read, compare, delete) and checkEndpointDns (the written form plus the DNS answer: a private address is refused) serve every product.
• The registry opens the OpenDAL kinds and private kinds (ADR-005 amendment, krizaka-ts#239). google-drive and onedrive are implemented at user scope (through opendalStore and CLOUD_CONNECTORS: the access token is renewed from the sealed refresh token, a rotated one comes back through OpenContext.onRotate and is sealed again by the service); azblob, gcs, b2 and webdav at admin scope (their field names are OpenDAL's own options; a typed url field passes checkEndpoint and the DNS check). openProvider is now asynchronous. Each kind maps to its adapter in a table (BUILT_IN_ADAPTERS), never a branch. A private package adds a kind without touching the core: defaultProviderRegistry.with({ kind, open }) (or createProviderRegistry({ kinds, adapters })) returns a new registry; pass it to openProvider(…, registry) and createProviderService({ registry }). A duplicate name is refused, a secret may not be a coordinate, a credential must be a secret field (sealed), and the runtime, devOnly, required-field and url rules apply to private kinds as to the built-in ones.
• Keyring is a port ({ keyId, wrap, unwrap, openLegacy? }). localKeyring({ keyId, key, ring }) is the in-process default (the old Keyring shape { keys, legacy } is now LocalKeys); sealWith, openWith and rewrapWith take any keyring, so a KMS (AWS KMS ca-central-1, OVHcloud KMS, Vault transit) wraps the data key and the key never reaches the app. createProviderService({ vault }) takes either the old { keyId, key, ring } or a Keyring. The stored v2.<key_id>… format is unchanged: moving to a KMS is rotateVaultKey, not a re-entry.
• Envelope vault. sealEnvelope/openEnvelope/rewrapEnvelope: a data key per sealed value, wrapped by the key-encryption key (MEDIA_VAULT_KEY) named by a key_id (v2.<key_id>.<wrapped>.<sealed>); v1. values still open with the legacy key; rotating the key re-wraps the data keys only.
• Providers in the database (@krizaka/storage/provider-admin, ADR-005 slice 2). storageSchema (tables storage.provider and storage.default_provider), dbProviderStore/memoryProviderStore (contract: providerStoreContract), and createProviderService: create (a draft, secrets sealed in an envelope), test (only a green test verifies), setDefault (verified only; the previous default becomes retiring), changeKey (the candidate is tested first), disable/retire (refused while the product still holds objects there), rotateVaultKey, bootstrap (imports the old MEDIA_* environment once as an active provider, source: env). Secrets come back as set/not set only; every change goes to the injected audit with secret fields as changed. moveBatch (get, check the SHA-256, put, read back and compare, then switch the row in the product transaction; failures are returned, never switched) and readDual (the row provider, then the retiring ones) are the move and the dual read.
• Users' own clouds (ADR-005 slice 4). dropboxStore (dropbox kind, user scope): App folder only, upload sessions above 150 MB, no signed or public link (Dropbox links outlive our 900 s cap, so the application streams). pkcePair, dropboxAuthorizeUrl, exchangeDropboxCode, refreshDropboxToken, revokeDropbox are the OAuth 2 PKCE steps; the refresh token is sealed like any credential, and a revoked or expired one answers STORAGE_DISCONNECTED (nothing is moved or deleted). A user's own S3 is the same s3 kind at user:<id> scope, with the DNS check of its endpoint.
• Every classic cloud through libraries (ADR-005 amendment, krizaka-ts#235). opendalStore (@krizaka/storage/opendal) is one adapter over Apache OpenDAL for Google Drive, OneDrive, Dropbox, Azure Blob, GCS, B2, Swift and WebDAV. Only the services of OPENDAL_SERVICES open; fs/memory need allowLocal; a typed endpoint passes checkEndpoint and the DNS check first. OpenDAL's errors map onto STORAGE_* (PermissionDenied on an OAuth cloud → STORAGE_DISCONNECTED), and readStream(key) streams large files. opendal is an optional peer (a native module of 59–82 MB, glibc ≥ 2.38 or musl), loaded on first use. CLOUD_CONNECTORS (/node) is the table of user clouds (Dropbox, Google Drive, OneDrive: endpoints, narrowest scope, revocation style). startConnection, finishConnection, refreshConnection, revokeConnection run Arctic's authorization code + PKCE S256, and connectionAccessToken feeds opendalStore a fresh access token and hands a rotated refresh token back to be resealed. dropboxStore and its helpers are superseded and stay until the products move.
• Signatures. SigV4 is checked against AWS's published vectors. The token form of the HTTP zone's signed links (SHA-256 of key + path + expires, URL-safe base64) is the one Yomizaka runs against Bunny's pull zones; Bunny's documentation publishes no expected output for it.

import { createStorage, defineLayout, folderStore } from "@krizaka/storage";
import { limitsOf, readStorageSettings, storeFromSettings } from "@krizaka/storage/settings";

const settings = await readStorageSettings((key) => service.get(key, ctx));
const storage = createStorage({
  store: storeFromSettings(settings, { accessKeyId: env.MEDIA_STORAGE_ACCESS_KEY_ID, secretAccessKey: env.MEDIA_STORAGE_SECRET }, { fetch, clock }),
  layout: defineLayout(["people/", "site/home/"]),
  limits: () => readStorageSettings(read).then(limitsOf),
});
const { key, url } = await storage.upload({ prefix: "people/", name: "ana.jpg", bytes, allow: ["image/jpeg", "image/png"], declaredType: file.type });

Apache-2.0.

ExportsCopy Anchor Link

The 49 names the package exports, read from its types.

@krizaka/storage/nodeCopy Anchor Link

@krizaka/storage/settingsCopy Anchor Link

@krizaka/storage/resolveCopy Anchor Link

@krizaka/storage/testkitCopy Anchor Link

@krizaka/storage/provider-adminCopy Anchor Link

@krizaka/storage/opendalCopy Anchor Link

PackageCopy Anchor Link

ChangelogCopy Anchor Link

0.8.1Copy Anchor Link

Patch changes

• The READMEs, comments and published declarations no longer name the products that left the organisation (krizaka/.github#413, rule no-departed-published). The sources were cleaned in #262 with an empty changeset, so the published tarballs still carried the old text; this release replaces them. No behaviour change.
• Updated dependencies [2272b57]
  • @krizaka/[email protected]

0.8.0Copy Anchor Link

Minor changes

• Every classic cloud through libraries (ADR-005 amendment, #235): opendalStore (@krizaka/storage/opendal, Apache OpenDAL as an optional peer) behind the port, with an allow-list of services, the endpoint and DNS checks kept, error mapping onto STORAGE_* and readStream; CLOUD_CONNECTORS and the Arctic-based connection flow (authorization code + PKCE S256, refresh with rotation, revocation) for Dropbox, Google Drive and OneDrive.
• The registry opens the OpenDAL kinds and takes private kinds (ADR-005 amendment, #239): google-drive and onedrive implemented at user scope, azblob, gcs, b2 and webdav at admin scope, each kind mapped to its adapter through a table; createProviderRegistry({ kinds, adapters }).with({ kind, open }) registers a private provider without touching the core (every rule applies: scopes, runtimes, devOnly, url fields checked, secrets sealed); Keyring becomes a port ({ keyId, wrap, unwrap }, localKeyring the default, sealWith/openWith/rewrapWith), ready for a KMS with the stored v2.<key_id> format unchanged. Breaking for 0.x consumers: openProvider is asynchronous, and the old Keyring type ({ keys, legacy }) is renamed LocalKeys.

Patch changes

• Updated dependencies [ce40b60]
  • @krizaka/[email protected]

0.7.0Copy Anchor Link

Minor changes

• storageSettings has storage.userConnectors (flag, off by default): the admin's policy on whether people may connect their own cloud (Dropbox, an S3 of their own). userConnectorsAllowed(read) reads it; anything but an explicit true is off.

Patch changes

• Updated dependencies [0d19b64]
  • @krizaka/[email protected]
  • @krizaka/[email protected]

0.6.0Copy Anchor Link

Minor changes

• Dropbox as a user-scope provider (ADR-005, slice 4): dropboxStore (App folder, upload sessions above 150 MB, no signed or public link: the app streams), the OAuth 2 PKCE helpers (pkcePair, dropboxAuthorizeUrl, exchangeDropboxCode, refreshDropboxToken, revokeDropbox), the new code STORAGE_DISCONNECTED for a revoked or expired connection, and dropbox opened by openProvider.
• Providers in the database (ADR-005, slice 2), in @krizaka/storage/provider-admin: storageSchema, dbProviderStore / memoryProviderStore with a contract, createProviderService (create, test, set default, change key, disable, retire, rotate the vault key, bootstrap from the environment; secrets returned as set / not set, every change audited), moveBatch (SHA-256-verified move) and readDual (reads from both stores during a move).

0.5.0Copy Anchor Link

Minor changes

• Provider registry (ADR-005, slice 1): PROVIDER_KINDS as data, openProvider with the runtime and environment guards (devOnly refused in prod, folder only in dev), PROVINCE_OF_REGION and residencyLabel, testConnection and checkEndpointDns moved from Yomizaka, and the envelope vault (sealEnvelope, openEnvelope, rewrapEnvelope, keyIdOf, v2. values with a key_id; v1. still opens).

0.4.0Copy Anchor Link

Minor changes

• sweepOrphans(store, prefix, isReferenced, { dryRun, limit }): deletes the files under a prefix that nothing references (leftovers of a rolled-back upload or an interrupted purge), reports scanned / orphans / deleted / failed, never stops on one failing delete.

0.3.1Copy Anchor Link

Patch changes

• The default entry is safe on Edge and in the browser: no node: import, nothing reads a file. It carries the types and the port, the region table, describeStore, storageNotice, the endpoint check, sniffType, the key rules and the in-memory store. The adapters that hash, sign, encrypt or touch the disk (createStorage, bucketStore, remoteStore, folderStore, encryptedStore, hashedName, seal/open) are in @krizaka/storage/node, and . still resolves to them under the node condition, so Node code keeps working unchanged. A test bundles the default entry for the browser and fails on any node: or fs import.

0.3.0Copy Anchor Link

Minor changes

• The four pieces Yomizaka kept locally move in (#146), and the admin-over-environment rule is decided. encryptedStore(inner, key) (AES-256-GCM over any ObjectStore, key as a parameter, ciphertext only at the provider, signedUrl/publicUrl null) with parseEncryptionKey; the vault seal/open/parseVaultKey for credentials in the database; the shared region table COUNTRY_OF_REGION with countryOf, residencyOf and residencyOfConfig (Canada only when the region AND the endpoint agree, never for a Bunny-shaped zone or an unmapped region); where(kind, active, { fixed, devOnly }), describeStore and storageNotice (the generated residency sentence, from the configuration). New subpath @krizaka/storage/resolve: resolveStorage(env, admin) applies the admin's storage.* settings over the deployment's environment for any kind of data (documents, avatars), caps the signed link, and openResolved builds the store (encrypted when a key is given). When the environment says none and the admin turns keeping on, resolveStorage throws StorageError STORAGE_KEEPING_OFF (new codes STORAGE_KEEPING_OFF, STORAGE_UNREADABLE, STORAGE_BAD_SECRET_KEY): keeping is only turned on from the environment.

0.2.0Copy Anchor Link

Minor changes

• New packages (#44). @krizaka/storage: the ObjectStore port (put, get, head, delete, list, signedUrl, publicUrl), remoteStore (HTTP zone, token-signed links), bucketStore (any S3-compatible service, Signature V4 checked against AWS's vectors), folderStore, memoryObjectStore, createStorage (size limit passed in, declared layout, magic-number check, content-hashed names), checkEndpoint, @krizaka/storage/settings (storage.provider local / http / s3, limits and coordinates; storeFromSettings) and objectStoreContract. @krizaka/video: the VideoProvider port, streamVideo (Bunny Stream: create, delete, server-signed TUS sessions, embed and mobile view tokens, signed HLS and poster links, signed webhooks), the signing helpers and videoProviderContract.