From 2fdd9571d6bbd71fd9a492bc6d060625ee89dbd0 Mon Sep 17 00:00:00 2001 From: stack72 Date: Wed, 18 Mar 2026 01:58:30 +0000 Subject: [PATCH] Improve vault extension documentation and configSchema field descriptions - Moved configSchema inline in the vault export for all three providers (1Password, AWS SM, Azure KV) so swamp.club's extension page correctly detects and displays config fields - Added .describe() to all configSchema fields with human-readable descriptions of each field's purpose - Used // deno-fmt-ignore to prevent deno fmt from wrapping single-line .describe() calls (multi-line breaks swamp.club's regex-based extractor) - Expanded all three manifest.yaml descriptions to rich multi-line Markdown, covering prerequisites, authentication, required permissions, usage examples, and secret key format --- .../extensions/vaults/onepassword.ts | 12 +++---- vault/1password/manifest.yaml | 30 ++++++++++++++-- vault/aws-sm/extensions/vaults/aws_sm.ts | 11 +++--- vault/aws-sm/manifest.yaml | 36 +++++++++++++++++-- vault/azure-kv/extensions/vaults/azure_kv.ts | 14 ++++---- vault/azure-kv/manifest.yaml | 31 ++++++++++++++-- 6 files changed, 108 insertions(+), 26 deletions(-) diff --git a/vault/1password/extensions/vaults/onepassword.ts b/vault/1password/extensions/vaults/onepassword.ts index 6d69afb..fd64386 100644 --- a/vault/1password/extensions/vaults/onepassword.ts +++ b/vault/1password/extensions/vaults/onepassword.ts @@ -19,11 +19,6 @@ import { z } from "npm:zod@4.3.6"; -const configSchema = z.object({ - op_vault: z.string().min(1, "1Password vault name is required"), - op_account: z.string().optional(), -}); - interface VaultProvider { get(secretKey: string): Promise; put(secretKey: string, secretValue: string): Promise; @@ -264,12 +259,15 @@ export const vault = { name: "1Password", description: "1Password vault provider. Uses the 1Password CLI (op) for secret operations.", - configSchema, + configSchema: z.object({ + op_vault: z.string().min(1).describe("The 1Password vault to use"), + op_account: z.string().optional().describe("Account shorthand or UUID"), + }), createProvider( name: string, config: Record, ): VaultProvider { - const parsed = configSchema.parse(config); + const parsed = vault.configSchema.parse(config); return new OnePasswordVaultProvider(name, parsed); }, }; diff --git a/vault/1password/manifest.yaml b/vault/1password/manifest.yaml index b54c05a..b0ba25d 100644 --- a/vault/1password/manifest.yaml +++ b/vault/1password/manifest.yaml @@ -1,7 +1,33 @@ manifestVersion: 1 name: "@swamp/1password" -version: "2026.03.17.1" -description: "1Password vault provider — uses the op CLI for secret operations" +version: "2026.03.18.5" +description: | + Read and write secrets stored in 1Password using the `op` CLI. + + ## Prerequisites + + - [1Password CLI](https://developer.1password.com/docs/cli/get-started/) installed and in `PATH` + - Authenticated via one of: + - **Service account**: `export OP_SERVICE_ACCOUNT_TOKEN=` + - **Desktop app**: enable CLI integration in 1Password settings + - **Connect Server**: `export OP_CONNECT_HOST=` and `export OP_CONNECT_TOKEN=` + + ## Usage + + ```bash + swamp vault create @swamp/1password my-1password \ + --config '{"op_vault": "Private"}' --json + + swamp vault get my-1password my-api-key --json + swamp vault put my-1password my-api-key "s3cr3t" --json + swamp vault list-keys my-1password --json + ``` + + ## Secret Key Format + + - `item-name` — reads the `password` field of the named item + - `item-name/field` — reads a specific field + - `op://vault/item/field` — full 1Password URI (passthrough) repository: "https://github.com/systeminit/swamp-extensions" vaults: - onepassword.ts diff --git a/vault/aws-sm/extensions/vaults/aws_sm.ts b/vault/aws-sm/extensions/vaults/aws_sm.ts index 21b67bd..7d19f02 100644 --- a/vault/aws-sm/extensions/vaults/aws_sm.ts +++ b/vault/aws-sm/extensions/vaults/aws_sm.ts @@ -27,10 +27,6 @@ import { SecretsManagerClient, } from "npm:@aws-sdk/client-secrets-manager@3.1010.0"; -const configSchema = z.object({ - region: z.string().min(1, "AWS region is required"), -}); - interface VaultProvider { get(secretKey: string): Promise; put(secretKey: string, secretValue: string): Promise; @@ -115,12 +111,15 @@ export const vault = { name: "AWS Secrets Manager", description: "AWS Secrets Manager vault provider. Uses the default AWS credential chain for authentication.", - configSchema, + configSchema: z.object({ + // deno-fmt-ignore + region: z.string().min(1).describe("AWS region where the Secrets Manager secrets are stored e.g. us-east-1"), + }), createProvider( name: string, config: Record, ): VaultProvider { - const parsed = configSchema.parse(config); + const parsed = vault.configSchema.parse(config); return new AwsSmVaultProvider(name, parsed); }, }; diff --git a/vault/aws-sm/manifest.yaml b/vault/aws-sm/manifest.yaml index 24ec86c..100e4b5 100644 --- a/vault/aws-sm/manifest.yaml +++ b/vault/aws-sm/manifest.yaml @@ -1,7 +1,39 @@ manifestVersion: 1 name: "@swamp/aws-sm" -version: "2026.03.17.1" -description: "AWS Secrets Manager vault provider" +version: "2026.03.18.1" +description: | + Read and write secrets stored in AWS Secrets Manager. + + ## Authentication + + Uses the default AWS credential chain — no credentials in config. Provide + credentials via one of: + - Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` + - AWS profile: `~/.aws/credentials` + - IAM role attached to the instance or task + + ## Required IAM Permissions + + - `secretsmanager:GetSecretValue` + - `secretsmanager:PutSecretValue` + - `secretsmanager:CreateSecret` + - `secretsmanager:ListSecrets` + + ## Usage + + ```bash + swamp vault create @swamp/aws-sm my-aws-sm \ + --config '{"region": "us-east-1"}' --json + + swamp vault get my-aws-sm my/secret/name --json + swamp vault put my-aws-sm my/secret/name "s3cr3t" --json + swamp vault list-keys my-aws-sm --json + ``` + + ## Secret Key Format + + Secret keys map directly to AWS Secrets Manager secret names, including + path-style names such as `myapp/production/db-password`. repository: "https://github.com/systeminit/swamp-extensions" vaults: - aws_sm.ts diff --git a/vault/azure-kv/extensions/vaults/azure_kv.ts b/vault/azure-kv/extensions/vaults/azure_kv.ts index c296ab2..ec4d449 100644 --- a/vault/azure-kv/extensions/vaults/azure_kv.ts +++ b/vault/azure-kv/extensions/vaults/azure_kv.ts @@ -21,11 +21,6 @@ import { z } from "npm:zod@4.3.6"; import { DefaultAzureCredential } from "npm:@azure/identity@4.13.0"; import { SecretClient } from "npm:@azure/keyvault-secrets@4.10.0"; -const configSchema = z.object({ - vault_url: z.string().url("Azure Key Vault URL is required"), - secret_prefix: z.string().optional(), -}); - interface VaultProvider { get(secretKey: string): Promise; put(secretKey: string, secretValue: string): Promise; @@ -107,12 +102,17 @@ export const vault = { name: "Azure Key Vault", description: "Azure Key Vault vault provider. Uses DefaultAzureCredential for authentication.", - configSchema, + configSchema: z.object({ + // deno-fmt-ignore + vault_url: z.string().url("Azure Key Vault URL is required").describe("Full URL of the Azure Key Vault e.g. https://my-vault.vault.azure.net"), + // deno-fmt-ignore + secret_prefix: z.string().optional().describe("Optional prefix to namespace secrets within the vault e.g. swamp- to scope all reads and writes"), + }), createProvider( name: string, config: Record, ): VaultProvider { - const parsed = configSchema.parse(config); + const parsed = vault.configSchema.parse(config); return new AzureKvVaultProvider(name, parsed); }, }; diff --git a/vault/azure-kv/manifest.yaml b/vault/azure-kv/manifest.yaml index d82ca17..2de4106 100644 --- a/vault/azure-kv/manifest.yaml +++ b/vault/azure-kv/manifest.yaml @@ -1,7 +1,34 @@ manifestVersion: 1 name: "@swamp/azure-kv" -version: "2026.03.17.1" -description: "Azure Key Vault vault provider" +version: "2026.03.18.1" +description: | + Read and write secrets stored in Azure Key Vault. + + ## Authentication + + Uses `DefaultAzureCredential` — no credentials in config. Provide + credentials via one of: + - Environment variables: `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET` + - Azure CLI: `az login` + - Managed Identity attached to the VM or container + + ## Usage + + ```bash + swamp vault create @swamp/azure-kv my-azure-kv \ + --config '{"vault_url": "https://my-vault.vault.azure.net"}' --json + + swamp vault get my-azure-kv my-secret --json + swamp vault put my-azure-kv my-secret "s3cr3t" --json + swamp vault list-keys my-azure-kv --json + ``` + + ## Secret Key Format + + Secret keys map to Azure Key Vault secret names. Slashes and underscores are + converted to hyphens (Azure only allows alphanumeric characters and hyphens). + Use `secret_prefix` to namespace secrets when sharing a vault across multiple + swamp instances. repository: "https://github.com/systeminit/swamp-extensions" vaults: - azure_kv.ts