- nzip vault add <name> --description TEXT - nzip vault update <name> --name NEW --description TEXT (empty clears) - descriptions shown in vault ls, vault ls --json, and status - renames update the invoking client's default vault and allow-list - D1 migration 0004_vault_descriptions.sql plus runtime coverage
- commit
- d14c5178f9876fc17e80c89129e7317663861dcf
- parent
- 890b49b482be9f441510ae26e5a551d7b8b19194
- author
- Dami <dami.etoile@gmail.com>
| M | README.md | 11 | +++++- |
| M | cli/ | 8 | ++++- |
| M | cli/ | 9 | ++++- |
| M | cli/ | 40 | ++++++++++++++++++-- |
| M | cli/ | 15 | +++++++- |
| M | cli/ | 9 | +++-- |
| M | shared/ | 2 | + |
| A | worker/ | 1 | + |
| M | worker/ | 1 | + |
| M | worker/ | 5 | ++- |
| M | worker/ | 5 | ++- |
| M | worker/ | 51 | ++++++++++++++++++++++++-- |
| M | worker/ | 52 | +++++++++++++++++++++------ |
| M | worker/ | 59 | +++++++++++++++++++++++++++--- |
@@ -74,7 +74,10 @@ Commands accept any of three target forms:
7474 7575 ```text7676 nzip auth [--server URL] [--token T] authenticate and save config77-nzip vault add <name> [--slot N] register a vault (16 slots, 0x0–0xf)77+nzip vault add <name> [--slot N] [--description TEXT]78+ register a vault (16 slots, 0x0–0xf)79+nzip vault update <name> [--name NEW_NAME] [--description TEXT]80+ rename or describe a vault7881 nzip vault ls | default <name> list vaults / set the default7982 nzip push <dir|file> [target] [--ttl …] [--password PW | --no-password]8083 nzip cp <target> [dir] [--overwrite] copy the current hosted bundle locally@@ -86,6 +89,10 @@ nzip status server + vault overview
8689 nzip revert <target> [--to N] [--list] repoint to a previous push8790 ```8891 92+Vault descriptions are returned by `vault ls --json` so agents can choose an93+appropriate destination from its purpose or audience. Pass an empty description94+to `vault update` to clear it.95+8996 Password and TTL are committed with the content. On a new site, omitting9097 `--password` creates an unprotected site; on an existing target, omission9198 preserves its current password. Pass `--no-password` to clear protection@@ -194,7 +201,7 @@ Content metadata lives in three tables:
194201 195202 | table | keys |196203 | -------- | -------------------------------------------------------------------------------- |197-| `vaults` | slot (0–15), name |204+| `vaults` | slot (0–15), name, optional description |198205 | `sites` | address (0–65535), vault, alias, current manifest, expiry, password hash/version |199206 | `pushes` | per-site history (seq, manifest, note), capped at 10, powers `revert` |200207 @@ -38,7 +38,10 @@ and site is already there.
3838 3939 ```text4040 nzip auth [--server URL] [--token T] authenticate and save config41-nzip vault add <name> [--slot N] register a vault (16 slots, 0x0–0xf)41+nzip vault add <name> [--slot N] [--description TEXT]42+ register a vault (16 slots, 0x0–0xf)43+nzip vault update <name> [--name NEW_NAME] [--description TEXT]44+ rename or describe a vault4245 nzip vault ls | default <name> list vaults / set the default4346 nzip push <dir|file> [target] [--ttl …] [--password PW | --no-password]4447 nzip cp <target> [dir] [--overwrite]@@ -50,6 +53,9 @@ nzip status server + vault overview
5053 nzip revert <target> [--to N] [--list] repoint to a previous push5154 ```5255 56+Vault descriptions are included in `vault ls --json`. Use57+`nzip vault update <name> --description ""` to clear one.58+5359 Password and TTL are committed with the content. On a new site, omitting `--password` creates an5460 unprotected site; on an existing target, omission preserves its current password. Pass5561 `--no-password` to clear protection explicitly. The former `nzip share` command remains available as@@ -141,10 +141,15 @@ export async function cmdStatus(config: Config): Promise<void> {
141141 );142142 if (status.vaults.length > 0) {143143 console.log(table(144- ["SLOT", "VAULT", "SITES"],144+ ["SLOT", "VAULT", "DESCRIPTION", "SITES"],145145 status.vaults.map((146146 v,147- ) => [`0x${v.slot.toString(16)}`, v.name, String(v.siteCount)]),147+ ) => [148+ `0x${v.slot.toString(16)}`,149+ v.name,150+ v.description ?? "",151+ String(v.siteCount),152+ ]),148153 ));149154 }150155 }, { ...status, server: config.server });@@ -8,6 +8,8 @@ export async function cmdVault(
88 sub: string | undefined,99 name: string | undefined,1010 slot: number | undefined,11+ newName: string | undefined,12+ description: string | undefined,1113 ): Promise<void> {1214 const api = new ApiClient(config);1315 @@ -19,10 +21,11 @@ export async function cmdVault(
1921 return;2022 }2123 console.log(table(22- ["SLOT", "VAULT", "SITES"],24+ ["SLOT", "VAULT", "DESCRIPTION", "SITES"],2325 vaults.map((v) => [2426 `0x${v.slot.toString(16)}`,2527 v.name === config.defaultVault ? bold(`${v.name} *`) : v.name,28+ v.description ?? "",2629 String(v.siteCount),2730 ]),2831 ));@@ -31,13 +34,13 @@ export async function cmdVault(
3134 }3235 3336 if (sub === "add") {34- if (!name) fail("usage: nzip vault add <name> [--slot N]");37+ if (!name) fail("usage: nzip vault add <name> [--slot N] [--description TEXT]");3538 try {3639 assertVaultAllowed(name, config);3740 } catch (e) {3841 return fail((e as Error).message);3942 }40- const v = await api.createVault(name, slot);43+ const v = await api.createVault(name, slot, description);4144 const madeDefault = !config.defaultVault;4245 if (madeDefault) await saveConfig({ ...config, defaultVault: v.name });4346 emit(() => {@@ -53,6 +56,35 @@ export async function cmdVault(
5356 return;5457 }5558 59+ if (sub === "update") {60+ if (!name || (newName === undefined && description === undefined)) {61+ fail("usage: nzip vault update <name> [--name NEW_NAME] [--description TEXT]");62+ }63+ try {64+ assertVaultAllowed(name, config);65+ } catch (e) {66+ return fail((e as Error).message);67+ }68+ const v = await api.updateVault(name, { name: newName, description });69+ if (newName !== undefined && newName !== name) {70+ await saveConfig({71+ ...config,72+ ...(config.defaultVault === name ? { defaultVault: newName } : {}),73+ ...(config.allowVaults74+ ? { allowVaults: config.allowVaults.map((vault) => vault === name ? newName : vault) }75+ : {}),76+ });77+ }78+ emit(79+ () =>80+ console.log(81+ `${green("✓")} vault ${bold(name)} updated${newName ? ` as ${bold(newName)}` : ""}`,82+ ),83+ { ok: true, ...v },84+ );85+ return;86+ }87+5688 if (sub === "default") {5789 if (!name) fail("usage: nzip vault default <name>");5890 try {@@ -70,5 +102,5 @@ export async function cmdVault(
70102 return;71103 }72104 73- fail(`unknown vault subcommand: ${sub} (use ls | add | default)`);105+ fail(`unknown vault subcommand: ${sub} (use ls | add | update | default)`);74106 }@@ -144,8 +144,19 @@ export class ApiClient {
144144 return this.request("GET", "/api/vaults");145145 }146146 147- createVault(name: string, slot?: number): Promise<VaultInfo> {148- return this.request("POST", "/api/vaults", JSON.stringify({ name, slot }));147+ createVault(name: string, slot?: number, description?: string): Promise<VaultInfo> {148+ return this.request("POST", "/api/vaults", JSON.stringify({ name, slot, description }));149+ }150+151+ updateVault(152+ currentName: string,153+ patch: { name?: string; description?: string },154+ ): Promise<VaultInfo> {155+ return this.request(156+ "PATCH",157+ `/api/vaults/${encodeURIComponent(currentName)}`,158+ JSON.stringify(patch),159+ );149160 }150161 }151162 @@ -31,7 +31,10 @@ const HELP = `nzip — html share tool
3131 3232 usage:3333 nzip auth [--server URL] [--token T] authenticate against the server34- nzip vault add <name> [--slot N] register a vault (16 slots, 0x0-0xf)34+ nzip vault add <name> [--slot N] [--description TEXT]35+ register a vault (16 slots, 0x0-0xf)36+ nzip vault update <name> [--name NEW_NAME] [--description TEXT]37+ rename or describe a vault3538 nzip vault ls list vaults3639 nzip vault default <name> set default vault3740 nzip push <dir|file> [target] [--ttl ...] [--password PW | --no-password]@@ -56,7 +59,7 @@ to named vaults — pushes/aliases outside the list are refused (agent guardrail
5659 5760 async function main(): Promise<void> {5861 const args = parseArgs(Deno.args, {59- string: ["ttl", "to", "slot", "server", "token", "password"],62+ string: ["ttl", "to", "slot", "server", "token", "password", "name", "description"],6063 boolean: ["yes", "list", "help", "no-password", "overwrite", "json"],6164 alias: { h: "help", y: "yes" },6265 });@@ -107,7 +110,7 @@ async function main(): Promise<void> {
107110 case "revert":108111 return await cmdRevert(config, rest[0], toSeq, args.list);109112 case "vault":110- return await cmdVault(config, rest[0], rest[1], slot);113+ return await cmdVault(config, rest[0], rest[1], slot, args.name, args.description);111114 default:112115 fail(`unknown command: ${command}\n\n${HELP}`);113116 }@@ -130,6 +130,8 @@ export interface VaultInfo {
130130 slot: number;131131 /** Registered lowercase vault name. */132132 name: string;133+ /** Optional context describing the vault's intended audience or purpose. */134+ description: string | null;133135 /** Unix timestamp, in seconds, when the vault was registered. */134136 createdAt: number;135137 /** Number of currently live sites assigned to this vault. */@@ -0,0 +1 @@
1+ALTER TABLE vaults ADD COLUMN description TEXT;@@ -65,8 +65,8 @@ Click the verification link Cloudflare sends, then configure:
6565 ```6666 6767 Apply `migrations/0002_security_alerts.sql` and68-`migrations/0003_security_notification_outbox.sql` before deploying an upgraded69-Worker.68+`migrations/0003_security_notification_outbox.sql`, then69+`migrations/0004_vault_descriptions.sql` before deploying an upgraded Worker.7070 After deployment, send a delivery test through the owner-authenticated endpoint:7171 7272 ```sh@@ -109,6 +109,7 @@ cd worker
109109 npx wrangler d1 execute nzip --remote --file migrations/0001_auth_version.sql110110 npx wrangler d1 execute nzip --remote --file migrations/0002_security_alerts.sql111111 npx wrangler d1 execute nzip --remote --file migrations/0003_security_notification_outbox.sql112+npx wrangler d1 execute nzip --remote --file migrations/0004_vault_descriptions.sql112113 ```113114 114115 > **Cron gotcha:** deploying the `triggers` block fails with a 403 (API error@@ -4,7 +4,7 @@ import { ApiError, apiErrorResponse } from "./api/errors.ts";
44 import { handleBlobPut, handleCommit, handlePrepare } from "./api/push.ts";55 import { handleSite, handleSiteList } from "./api/sites.ts";66 import { handleStatus } from "./api/status.ts";7-import { handleVaults } from "./api/vaults.ts";7+import { handleVault, handleVaults } from "./api/vaults.ts";88 import { sendAlertTest } from "./security_alerts.ts";99 1010 /** Authenticated management API router. Route handlers own validation and storage concerns. */@@ -42,6 +42,9 @@ export async function api(
4242 ) {4343 return await handleVaults(request, env);4444 }45+ if (parts[1] === "vaults" && parts.length === 3 && method === "PATCH") {46+ return await handleVault(request, env, parts[2]);47+ }4548 if (parts[1] === "sites" && parts.length === 2 && method === "GET") {4649 return await handleSiteList(url, env);4750 }@@ -1,27 +1,72 @@
11 import { isValidName, VAULT_SLOTS } from "../../../shared/mod.ts";2-import { createVault, listVaults } from "../db.ts";2+import { createVault, listVaults, updateVault } from "../db.ts";33 import { type Env, json } from "../env.ts";44 import { ApiError, readJson } from "./errors.ts";55 6+const DESCRIPTION_MAX_LENGTH = 500;7+8+function descriptionValue(value: unknown): string | null {9+ if (typeof value !== "string") {10+ throw new ApiError(400, "description must be a string");11+ }12+ const description = value.trim();13+ if (description.length > DESCRIPTION_MAX_LENGTH) {14+ throw new ApiError(400, `description must be at most ${DESCRIPTION_MAX_LENGTH} characters`);15+ }16+ return description || null;17+}18+619 export async function handleVaults(720 request: Request,821 env: Env,922 ): Promise<Response> {1023 if (request.method === "GET") return json(await listVaults(env));11- const body = await readJson<{ name: string; slot?: number }>(request);24+ const body = await readJson<{ name: string; slot?: number; description?: unknown }>(request);1225 if (!isValidName(body.name)) throw new ApiError(400, "invalid vault name");1326 if (body.slot !== undefined && (body.slot < 0 || body.slot >= VAULT_SLOTS)) {1427 throw new ApiError(400, "slot must be 0-15");1528 }29+ const description = body.description === undefined ? null : descriptionValue(body.description);1630 try {17- const vault = await createVault(env, body.name, body.slot);31+ const vault = await createVault(env, body.name, body.slot, description);1832 return json({1933 slot: vault.slot,2034 name: vault.name,35+ description: vault.description,2136 createdAt: vault.created_at,37+ siteCount: 0,2238 }, 201);2339 } catch (cause) {2440 const message = cause instanceof Error ? cause.message : "vault conflict";2541 throw new ApiError(409, message, { cause });2642 }2743 }44+45+export async function handleVault(46+ request: Request,47+ env: Env,48+ encodedName: string,49+): Promise<Response> {50+ if (request.method !== "PATCH") throw new ApiError(405, "method not allowed");51+ const currentName = decodeURIComponent(encodedName);52+ const body = await readJson<{ name?: unknown; description?: unknown }>(request);53+ if (body.name === undefined && body.description === undefined) {54+ throw new ApiError(400, "provide name and/or description");55+ }56+ if (body.name !== undefined && (typeof body.name !== "string" || !isValidName(body.name))) {57+ throw new ApiError(400, "invalid vault name");58+ }59+ const patch = {60+ ...(typeof body.name === "string" ? { name: body.name } : {}),61+ ...(body.description !== undefined ? { description: descriptionValue(body.description) } : {}),62+ };63+ try {64+ const vault = await updateVault(env, currentName, patch);65+ if (!vault) throw new ApiError(404, `unknown vault: ${currentName}`);66+ return json(vault);67+ } catch (cause) {68+ if (cause instanceof ApiError) throw cause;69+ const message = cause instanceof Error ? cause.message : "vault conflict";70+ throw new ApiError(409, message, { cause });71+ }72+}@@ -5,12 +5,7 @@ import {
55 VAULT_SLOTS,66 vaultSlotOf,77 } from "../../shared/mod.ts";8-import type {9- PushInfo,10- SiteDetail,11- SiteInfo,12- VaultInfo,13-} from "../../shared/mod.ts";8+import type { PushInfo, SiteDetail, SiteInfo, VaultInfo } from "../../shared/mod.ts";149 import { type Env, siteUrl } from "./env.ts";1510 1611 export const HISTORY_CAP = 10;@@ -30,6 +25,7 @@ export interface SiteRow {
3025 export interface VaultRow {3126 slot: number;3227 name: string;28+ description: string | null;3329 created_at: number;3430 }3531 @@ -201,15 +197,22 @@ export async function siteHistory(
201197 202198 export async function listVaults(env: Env): Promise<VaultInfo[]> {203199 const res = await env.DB.prepare(204- `SELECT v.slot, v.name, v.created_at, COUNT(s.address) AS site_count200+ `SELECT v.slot, v.name, v.description, v.created_at, COUNT(s.address) AS site_count205201 FROM vaults v LEFT JOIN sites s ON s.vault_slot = v.slot206202 GROUP BY v.slot ORDER BY v.slot`,207203 ).all<208- { slot: number; name: string; created_at: number; site_count: number }204+ {205+ slot: number;206+ name: string;207+ description: string | null;208+ created_at: number;209+ site_count: number;210+ }209211 >();210212 return res.results.map((r) => ({211213 slot: r.slot,212214 name: r.name,215+ description: r.description,213216 createdAt: r.created_at,214217 siteCount: r.site_count,215218 }));@@ -219,6 +222,7 @@ export async function createVault(
219222 env: Env,220223 name: string,221224 slot?: number,225+ description: string | null = null,222226 ): Promise<VaultRow> {223227 const now = Math.floor(Date.now() / 1000);224228 let chosen = slot;@@ -236,10 +240,36 @@ export async function createVault(
236240 if (chosen === undefined) throw new Error("all 16 vault slots are taken");237241 }238242 await env.DB.prepare(239- "INSERT INTO vaults (slot, name, created_at) VALUES (?, ?, ?)",243+ "INSERT INTO vaults (slot, name, description, created_at) VALUES (?, ?, ?, ?)",240244 )241- .bind(chosen, name, now).run();242- return { slot: chosen, name, created_at: now };245+ .bind(chosen, name, description, now).run();246+ return { slot: chosen, name, description, created_at: now };247+}248+249+export async function updateVault(250+ env: Env,251+ currentName: string,252+ patch: { name?: string; description?: string | null },253+): Promise<VaultInfo | null> {254+ const assignments: string[] = [];255+ const values: unknown[] = [];256+ if (patch.name !== undefined) {257+ assignments.push("name = ?");258+ values.push(patch.name);259+ }260+ if (patch.description !== undefined) {261+ assignments.push("description = ?");262+ values.push(patch.description);263+ }264+ if (assignments.length === 0) return null;265+266+ const result = await env.DB.prepare(267+ `UPDATE vaults SET ${assignments.join(", ")} WHERE name = ?`,268+ ).bind(...values, currentName).run();269+ if (result.meta.changes === 0) return null;270+271+ const updatedName = patch.name ?? currentName;272+ return (await listVaults(env)).find((vault) => vault.name === updatedName) ?? null;243273 }244274 245275 export function siteRowToInfo(@@ -1,9 +1,4 @@
1-import {2- createExecutionContext,3- env,4- SELF,5- waitOnExecutionContext,6-} from "cloudflare:test";1+import { createExecutionContext, env, SELF, waitOnExecutionContext } from "cloudflare:test";72 import { describe, expect, it } from "vitest";83 import worker from "../src/index.ts";94 import { hashPassword, verifyPassword } from "../src/password.ts";@@ -41,6 +36,58 @@ describe("Worker runtime", () => {
4136 expect((await response.json<{ version: string }>()).version).toBe("0.3.1");4237 });4338 39+ it("creates, lists, renames, and redescribes vaults", async () => {40+ const headers = {41+ authorization: "Bearer runtime-test-token",42+ "content-type": "application/json",43+ };44+ const created = await SELF.fetch("https://share.example.com/api/vaults", {45+ method: "POST",46+ headers,47+ body: JSON.stringify({48+ name: "agent-work",49+ description: "Scratch space for agent-generated review artifacts",50+ }),51+ });52+ expect(created.status).toBe(201);53+ expect(await created.json()).toMatchObject({54+ name: "agent-work",55+ description: "Scratch space for agent-generated review artifacts",56+ siteCount: 0,57+ });58+59+ const updated = await SELF.fetch(60+ "https://share.example.com/api/vaults/agent-work",61+ {62+ method: "PATCH",63+ headers,64+ body: JSON.stringify({65+ name: "reviews",66+ description: "Human review links; safe to share with collaborators",67+ }),68+ },69+ );70+ expect(updated.status).toBe(200);71+ expect(await updated.json()).toMatchObject({72+ name: "reviews",73+ description: "Human review links; safe to share with collaborators",74+ });75+76+ const listed = await SELF.fetch("https://share.example.com/api/vaults", { headers });77+ expect(await listed.json()).toContainEqual(expect.objectContaining({78+ name: "reviews",79+ description: "Human review links; safe to share with collaborators",80+ }));81+82+ const cleared = await SELF.fetch("https://share.example.com/api/vaults/reviews", {83+ method: "PATCH",84+ headers,85+ body: JSON.stringify({ description: "" }),86+ });87+ expect(cleared.status).toBe(200);88+ expect(await cleared.json()).toMatchObject({ name: "reviews", description: null });89+ });90+4491 it("evaluates a real D1 probe window through the scheduled handler", async () => {4592 const now = Math.floor(Date.now() / 300_000) * 300;4693 const bucket = now - 300;