@quarry-systems/mcg-secrets-ssm

AWS Systems Manager Parameter Store secrets adapter for MCG.

Features

• AWS SSM integration: Read secrets from Parameter Store
• Automatic decryption: SecureString parameters are decrypted automatically
• Caching: Optional in-memory cache with TTL
• Type-safe: Full TypeScript support
• Peer dependency: AWS SDK is a peer dependency (you control the version)

Installation

npm install @quarry-systems/mcg-secrets-ssm @aws-sdk/client-ssm

Usage

import { SSMClient } from '@aws-sdk/client-ssm';
import { createSSMSecretsAdapter } from '@quarry-systems/mcg-secrets-ssm';

// Create SSM client
const ssmClient = new SSMClient({ region: 'us-east-1' });

// Create adapter
const secrets = createSSMSecretsAdapter({
  client: ssmClient,
  prefix: '/myapp/',           // Optional: prepend to all keys
  cache: true,                 // Optional: enable caching
  cacheTtlMs: 300000          // Optional: cache TTL (5 min)
});

// Read parameter
// Fetches from /myapp/database/password
const dbPassword = await secrets.get({ key: 'database/password' });

Integration with MCG

import { ManagedCyclicGraph } from '@quarry-systems/managed-cyclic-graph';
import { SSMClient } from '@aws-sdk/client-ssm';
import { createSSMSecretsAdapter } from '@quarry-systems/mcg-secrets-ssm';

// Create secrets adapter
const ssmClient = new SSMClient({ region: 'us-east-1' });
const secrets = createSSMSecretsAdapter({
  client: ssmClient,
  prefix: '/myapp/'
});

// Build graph with secrets plugin
const graph = new ManagedCyclicGraph()
  .use({ services: { secrets } })
  .node('fetchData', {
    type: 'action',
    action: async (ctx, services) => {
      // Access secrets via services
      const apiKey = await services.secrets.get({ key: 'api/key' });
      
      const response = await fetch('https://api.example.com/data', {
        headers: { 'Authorization': `Bearer ${apiKey}` }
      });
      
      return { data: await response.json() };
    }
  })
  .build();

// Execute
await graph.run({ input: 'test' });

Configuration

interface SSMSecretsConfig {
  /** AWS SSM client instance */
  client: SSMClient;
  
  /** Optional prefix to prepend to all parameter names */
  prefix?: string;
  
  /** Enable in-memory caching (default: false) */
  cache?: boolean;
  
  /** Cache TTL in milliseconds (default: 300000 = 5 min) */
  cacheTtlMs?: number;
}

AWS Permissions

The IAM role/user needs:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter",
        "ssm:GetParameters",
        "ssm:DescribeParameters"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/myapp/*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Decrypt"
      ],
      "Resource": "arn:aws:kms:*:*:key/*"
    }
  ]
}

Testing

Tests use mocked SSM client:

npm test

License

MIT