@mstone6969/vault 0.2.0 → 0.5.0

package/docs/stores/sqlite/classes/SqliteStore.md

@@ -0,0 +1,307 @@
+[**@mstone6969/vault**](../../../README.md)
+
+***
+
+[@mstone6969/vault](../../../README.md) / [stores/sqlite](../README.md) / SqliteStore
+
+# Class: SqliteStore
+
+Defined in: cron/vault/src/stores/sqlite.ts:69
+
+Keeps records in SQLite through `bun:sqlite`. Pass a file path, ":memory:",
+or a Database you already opened.
+
+Values are sealed, but owners, names and metadata are ordinary columns —
+anyone who can read the file learns what you keep, if not what it says. Use
+`FileStore` when even that should be hidden.
+
+## Remarks
+
+`bun:sqlite` makes this store Bun-only: importing it on Node fails at the
+import, not at the first query. That is why it is reached through
+`@mstone6969/vault/stores/sqlite` instead of the package's main entry —
+a Node program that imports the main entry never loads this file, and never
+sees the Bun-only import.
+
+Every method is `async` only to satisfy [VaultStore](../../../index/type-aliases/VaultStore.md); `bun:sqlite` is
+synchronous, so nothing here waits on I/O.
+
+## Example
+
+```ts
+import { Vault } from "@mstone6969/vault"
+import { SqliteStore } from "@mstone6969/vault/stores/sqlite"
+
+const store = new SqliteStore("./vault.sqlite")
+const vault = new Vault({ key: process.env.VAULT_KEY!, store })
+
+await vault.put("alice", "db-password", "hunter2", {
+    metadata: { kind: "postgres" },
+})
+console.log(await vault.open("alice", "db-password")) // "hunter2"
+store.close()
+```
+
+## See
+
+[VaultStore](../../../index/type-aliases/VaultStore.md) for what a store owes the vault.
+
+## Implements
+
+- [`VaultStore`](../../../index/type-aliases/VaultStore.md)
+
+## Constructors
+
+### Constructor
+
+> **new SqliteStore**(`database?`, `table?`): `SqliteStore`
+
+Defined in: cron/vault/src/stores/sqlite.ts:106
+
+Opens the database if it was given a path, and makes sure the table is
+there and current.
+
+The table is created in its 0.1.0 shape if it is missing, and then every
+column added since — `sealed_key`, `plain`, `is_sealed`, `is_final`,
+`expires_at`, `history`, `rotation`, `rotated_at`, `metadata` — is
+ALTERed in if it is absent. So a table written by an older version of
+the package is upgraded the moment a newer one opens it, in place and
+without a migration step of your own, and rows that predate a column
+read back with sensible defaults: no history, no metadata, sealed, not
+final, no expiry.
+
+#### Parameters
+
+##### database?
+
+`string` \| `Database`
+
+A file path to open, ":memory:" for a database that
+  lasts as long as the process, or a `Database` you already opened —
+  useful for keeping the vault's table beside your own in one file, and
+  inside your own transactions.
+
+##### table?
+
+`string` = `"vault_secrets"`
+
+Which table to keep records in. Give it a name of its own
+  when one database holds several vaults.
+
+#### Returns
+
+`SqliteStore`
+
+#### Default Value
+
+`":memory:"`
+
+#### Default Value
+
+`"vault_secrets"`
+
+#### Throws
+
+Whatever `bun:sqlite` throws when the path cannot be opened, or
+  when `table` already exists with an incompatible shape.
+
+#### Example
+
+**Sharing a database you already opened**
+
+```ts
+import { Database } from "bun:sqlite"
+import { SqliteStore } from "@mstone6969/vault/stores/sqlite"
+
+const db = new Database("./app.sqlite")
+const store = new SqliteStore(db, "shared_secrets")
+```
+
+## Methods
+
+### get()
+
+> **get**(`owner`, `name`): `Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md) \| `null`\>
+
+Defined in: cron/vault/src/stores/sqlite.ts:181
+
+One record, or null when there is none under that name.
+
+The record carries the sealed value, not the plaintext: use
+`Vault.open` to get a value back out.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to look for.
+
+##### name
+
+`string`
+
+The entry's name.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md) \| `null`\>
+
+The stored record, or null when that owner has nothing under
+  that name.
+
+#### Implementation of
+
+`VaultStore.get`
+
+***
+
+### list()
+
+> **list**(`owner`): `Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/sqlite.ts:197
+
+Every record one owner holds, in whatever order SQLite returns them —
+the vault sorts what it shows.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entries to return.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)[]\>
+
+That owner's records, empty when they hold none.
+
+#### Implementation of
+
+`VaultStore.list`
+
+***
+
+### all()
+
+> **all**(): `Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)[]\>
+
+Defined in: cron/vault/src/stores/sqlite.ts:213
+
+Every record, whoever owns it.
+
+Only `Vault.rekey` and `Vault.purgeExpired` need this;
+everything else stays inside one owner. It loads the whole table, so it
+is the one method that costs more as the vault grows.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)[]\>
+
+Every record in the table.
+
+#### Implementation of
+
+`VaultStore.all`
+
+***
+
+### put()
+
+> **put**(`record`): `Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)\>
+
+Defined in: cron/vault/src/stores/sqlite.ts:235
+
+Writes a record, replacing any under the same owner and name.
+
+`created_at` is deliberately left out of the conflict update: a
+replacement keeps the moment the entry first appeared. Nothing here
+enforces finality or expiry — those are the vault's rules, and the store
+writes what it is given.
+
+#### Parameters
+
+##### record
+
+[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)
+
+The record to write. `owner` and `name` are its key.
+
+#### Returns
+
+`Promise`\<[`SecretRecord`](../../../index/type-aliases/SecretRecord.md)\>
+
+The record as it reads back out of SQLite, which is what
+  callers should keep — dates have been through epoch milliseconds and
+  JSON columns through a round trip.
+
+#### Throws
+
+Error if the row cannot be read back immediately after writing
+  it, which means the database is not behaving as SQLite.
+
+#### Implementation of
+
+`VaultStore.put`
+
+***
+
+### remove()
+
+> **remove**(`owner`, `name`): `Promise`\<`boolean`\>
+
+Defined in: cron/vault/src/stores/sqlite.ts:289
+
+Deletes a record, returning false when there was nothing to delete.
+
+History goes with it: the row holds the previous values, so deleting an
+entry deletes every version of it.
+
+#### Parameters
+
+##### owner
+
+`string`
+
+Whose entry to delete.
+
+##### name
+
+`string`
+
+The entry's name.
+
+#### Returns
+
+`Promise`\<`boolean`\>
+
+True when a record was there and is now gone, false when there
+  was nothing under that name.
+
+#### Implementation of
+
+`VaultStore.remove`
+
+***
+
+### close()
+
+> **close**(): `void`
+
+Defined in: cron/vault/src/stores/sqlite.ts:305
+
+Closes the underlying database.
+
+This closes a `Database` you passed to the constructor as well — the
+store does not track who opened it, so anything else using that same
+handle stops working too. Call it on the owner of the connection only.
+
+#### Returns
+
+`void`
+
+Nothing; the store is unusable afterwards.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mstone6969/vault",
-  "version": "0.2.0",
-  "description": "A write-only credential vault: AES-256-GCM at rest, per-owner scoping, and @vault: references resolved at use.",
+  "version": "0.5.0",
+  "description": "A write-only credential vault: envelope encryption, key rotation, expiry, history and an encrypted single-file store.",
   "type": "module",
   "license": "MIT",
   "author": "Malcolmston",
@@ -29,10 +29,15 @@
       "types": "./dist/stores/sqlite.d.ts",
       "import": "./dist/stores/sqlite.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./stores/file": {
+      "types": "./dist/stores/file.d.ts",
+      "import": "./dist/stores/file.js"
+    }
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
   "sideEffects": false,
@@ -46,10 +51,15 @@
     "build": "bun run build.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "bun run typecheck && bun test && bun run build"
+    "prepublishOnly": "bun run typecheck && bun run docs:check && bun run test:coverage && bun run build && bun run docs",
+    "test:coverage": "bun test --coverage",
+    "docs": "typedoc",
+    "docs:check": "typedoc --emit none"
   },
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "typedoc": "^0.28.20",
+    "typedoc-plugin-markdown": "^4.12.0"
   },
   "peerDependencies": {
     "typescript": "^5"