Compare commits
2 Commits
docs/merge
...
647fd9a835
| Author | SHA1 | Date | |
|---|---|---|---|
|
647fd9a835 | ||
|
|
b31699de81 |
@@ -137,97 +137,6 @@ describe('AppserviceDaemon routing', () => {
|
||||
expect(res.status).toBe(405);
|
||||
});
|
||||
|
||||
it('provisions a room as the AS sender with space linking', async () => {
|
||||
const calls: Array<{ url: URL; body: unknown }> = [];
|
||||
const fetchMock = vi.fn(async (input: URL | string, init?: RequestInit) => {
|
||||
const url = new URL(String(input));
|
||||
calls.push({ url, body: init?.body ? JSON.parse(String(init.body)) : undefined });
|
||||
if (url.pathname.endsWith('/createRoom'))
|
||||
return jsonResponse(200, { room_id: '!new:hs.example' });
|
||||
return jsonResponse(200, {});
|
||||
});
|
||||
const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
|
||||
const res = await daemon.handle(
|
||||
request({
|
||||
method: 'POST',
|
||||
path: '/bridge/v1/provision/rooms',
|
||||
authorizationHeader: 'Bearer bridge-secret',
|
||||
body: {
|
||||
name: 'proj-x',
|
||||
alias: 'mosaic-proj-x',
|
||||
invite: ['@jason.woltje:hs.example'],
|
||||
space_id: '!space:hs.example',
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.room_id).toBe('!new:hs.example');
|
||||
expect(res.body.space_linked).toBe(true);
|
||||
const create = calls.find((c) => c.url.pathname.endsWith('/createRoom'));
|
||||
expect(create!.url.searchParams.get('user_id')).toBe('@mosaic-as:hs.example');
|
||||
const body = create!.body as Record<string, unknown>;
|
||||
expect(body.room_alias_name).toBe('mosaic-proj-x');
|
||||
expect((body.power_level_content_override as Record<string, unknown>).users).toEqual({
|
||||
'@mosaic-as:hs.example': 100,
|
||||
});
|
||||
expect(calls.some((c) => c.url.pathname.includes('/state/m.space.child/'))).toBe(true);
|
||||
expect(calls.some((c) => c.url.pathname.includes('/state/m.space.parent/'))).toBe(true);
|
||||
});
|
||||
|
||||
it('space-link failure still returns the room id (no orphan)', async () => {
|
||||
const fetchMock = vi.fn(async (input: URL | string) => {
|
||||
const url = new URL(String(input));
|
||||
if (url.pathname.endsWith('/createRoom'))
|
||||
return jsonResponse(200, { room_id: '!new:hs.example' });
|
||||
if (url.pathname.includes('/state/m.space.child/'))
|
||||
return jsonResponse(403, { errcode: 'M_FORBIDDEN', error: 'no PL in space' });
|
||||
return jsonResponse(200, {});
|
||||
});
|
||||
const daemon = new AppserviceDaemon(cfg, fetchMock as unknown as typeof fetch, () => {});
|
||||
const res = await daemon.handle(
|
||||
request({
|
||||
method: 'POST',
|
||||
path: '/bridge/v1/provision/rooms',
|
||||
authorizationHeader: 'Bearer bridge-secret',
|
||||
body: { name: 'proj-x', space_id: '!space:hs.example' },
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
expect(res.body.room_id).toBe('!new:hs.example');
|
||||
expect(res.body.space_linked).toBe(false);
|
||||
expect(String(res.body.space_error)).toContain('403');
|
||||
});
|
||||
|
||||
it('invite list cap enforced', async () => {
|
||||
const { daemon } = makeDaemon();
|
||||
const res = await daemon.handle(
|
||||
request({
|
||||
method: 'POST',
|
||||
path: '/bridge/v1/provision/rooms',
|
||||
authorizationHeader: 'Bearer bridge-secret',
|
||||
body: { name: 'x', invite: Array.from({ length: 51 }, (_, i) => `@u${i}:hs`) },
|
||||
}),
|
||||
);
|
||||
expect(res.status).toBe(400);
|
||||
});
|
||||
|
||||
it('provision rejects bad payloads and requires auth', async () => {
|
||||
const { daemon } = makeDaemon();
|
||||
const noAuth = await daemon.handle(
|
||||
request({ method: 'POST', path: '/bridge/v1/provision/rooms', body: { name: 'x' } }),
|
||||
);
|
||||
expect(noAuth.status).toBe(403);
|
||||
const bad = await daemon.handle(
|
||||
request({
|
||||
method: 'POST',
|
||||
path: '/bridge/v1/provision/rooms',
|
||||
authorizationHeader: 'Bearer bridge-secret',
|
||||
body: { name: '', alias: 'BAD ALIAS' },
|
||||
}),
|
||||
);
|
||||
expect(bad.status).toBe(400);
|
||||
});
|
||||
|
||||
it('empty bridge token list denies everything', async () => {
|
||||
const daemon = new AppserviceDaemon({ ...cfg, bridgeTokens: [] }, undefined, () => {});
|
||||
const res = await daemon.handle(
|
||||
|
||||
@@ -5,7 +5,6 @@ import {
|
||||
TransactionHandler,
|
||||
validateBridgeMessage,
|
||||
validateBridgeTyping,
|
||||
validateProvisionRoom,
|
||||
} from '@mosaicstack/appservice';
|
||||
import type { AppserviceConfig, MatrixEvent } from '@mosaicstack/appservice';
|
||||
|
||||
@@ -110,27 +109,6 @@ export class AppserviceDaemon {
|
||||
await this.intent.setTyping(req.body.room_id, req.body.agent, req.body.typing);
|
||||
return { status: 200, body: {} };
|
||||
}
|
||||
if (req.method === 'POST' && req.path === '/bridge/v1/provision/rooms') {
|
||||
validateProvisionRoom(req.body);
|
||||
const result = await this.intent.createRoom({
|
||||
name: req.body.name,
|
||||
alias: req.body.alias,
|
||||
topic: req.body.topic,
|
||||
invite: req.body.invite,
|
||||
spaceId: req.body.space_id,
|
||||
});
|
||||
this.log(
|
||||
`provisioned room ${result.roomId} (${req.body.name}) space_linked=${result.spaceLinked}`,
|
||||
);
|
||||
return {
|
||||
status: 200,
|
||||
body: {
|
||||
room_id: result.roomId,
|
||||
space_linked: result.spaceLinked,
|
||||
...(result.spaceError ? { space_error: result.spaceError } : {}),
|
||||
},
|
||||
};
|
||||
}
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
this.log(`bridge error ${req.method} ${req.path}: ${message}`);
|
||||
|
||||
@@ -453,26 +453,6 @@ Initialize standard labels and the first pre-MVP milestone:
|
||||
|
||||
---
|
||||
|
||||
## Secrets Bootstrap (Required for Every New App)
|
||||
|
||||
Every new application MUST complete the following secrets bootstrap before deploying to any non-local environment. This is a hard gate — deployment without completed secrets bootstrap is forbidden.
|
||||
|
||||
### Secrets bootstrap checklist
|
||||
|
||||
- [ ] Vault path created: `vault kv put secret/k3s/<app>/ ...` with all required secret fields
|
||||
- [ ] Required secrets listed in project README under a "Secrets architecture" section, including:
|
||||
- Vault path(s) used
|
||||
- All required secret keys and their purpose
|
||||
- Whether the app uses ESO bridge (default) or Direct-Vault (opt-in, with justification)
|
||||
- [ ] `external-secret.yaml` manifest committed to repo's `deploy/` or `k8s/` directory
|
||||
- [ ] Deployment YAML references the synced k8s Secret via `secretKeyRef` (not raw env vars or `.env` files)
|
||||
- [ ] App startup has schema-based validation for all required env vars (zod / pydantic / envconfig equivalent) that exits non-zero on missing required values
|
||||
- [ ] Direct-Vault opt-in (if applicable): justification documented in README + AppRole provisioned + bootstrap credentials stored in Vault and synced via a separate `ExternalSecret`
|
||||
|
||||
See `~/.config/mosaic/guides/VAULT-SECRETS.md` for full worked examples of the ESO bridge pattern, the Direct-Vault opt-in pattern, and the forbidden antipatterns.
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
After bootstrapping, verify:
|
||||
|
||||
@@ -203,374 +203,3 @@ Error: token expired
|
||||
3. **Audit logging** - All access is logged; act accordingly
|
||||
4. **No local copies** - Don't store secrets in files or env vars long-term
|
||||
5. **Rotate on compromise** - Immediately rotate any exposed secrets
|
||||
|
||||
---
|
||||
|
||||
## Secrets Architecture Decision Matrix
|
||||
|
||||
Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
|
||||
|
||||
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
|
||||
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
|
||||
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
|
||||
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
|
||||
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
|
||||
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
|
||||
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
|
||||
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
|
||||
|
||||
**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
|
||||
|
||||
---
|
||||
|
||||
## ESO Bridge Pattern (Default)
|
||||
|
||||
This is the required default for all k8s workloads. Follow this exact pattern unless a documented dynamic-secrets requirement justifies Direct-Vault.
|
||||
|
||||
### 1. Provision Vault path
|
||||
|
||||
```bash
|
||||
# Write the secrets for the app (run once; use IaC/Terraform for repeatable provisioning)
|
||||
vault kv put secret/k3s/<app> \
|
||||
db_password="..." \
|
||||
api_key="..." \
|
||||
jwt_secret="..."
|
||||
```
|
||||
|
||||
Use the canonical path structure: `secret/k3s/<app>` for k3s cluster workloads.
|
||||
|
||||
### 2. ExternalSecret manifest
|
||||
|
||||
Commit this to the repo's `deploy/` or `k8s/` directory:
|
||||
|
||||
```yaml
|
||||
# deploy/external-secret.yaml
|
||||
apiVersion: external-secrets.io/v1beta1
|
||||
kind: ExternalSecret
|
||||
metadata:
|
||||
name: <app>-secrets
|
||||
namespace: <namespace>
|
||||
spec:
|
||||
refreshInterval: 1h
|
||||
secretStoreRef:
|
||||
name: vault-backend # ClusterSecretStore name — verify with cluster admin
|
||||
kind: ClusterSecretStore
|
||||
target:
|
||||
name: <app>-secrets # k8s Secret name that will be created
|
||||
creationPolicy: Owner
|
||||
data:
|
||||
- secretKey: DB_PASSWORD # key in the k8s Secret
|
||||
remoteRef:
|
||||
key: secret/k3s/<app> # Vault path
|
||||
property: db_password # field within the Vault secret
|
||||
- secretKey: API_KEY
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>
|
||||
property: api_key
|
||||
- secretKey: JWT_SECRET
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>
|
||||
property: jwt_secret
|
||||
```
|
||||
|
||||
### 3. Deployment manifest — reference synced k8s Secret
|
||||
|
||||
```yaml
|
||||
# deploy/deployment.yaml (env section)
|
||||
env:
|
||||
- name: DB_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets # matches ExternalSecret target.name
|
||||
key: DB_PASSWORD
|
||||
- name: API_KEY
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets
|
||||
key: API_KEY
|
||||
- name: JWT_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets
|
||||
key: JWT_SECRET
|
||||
- name: PORT
|
||||
value: '3000' # safe-default: non-secret, no Vault needed
|
||||
```
|
||||
|
||||
### 4. App-side schema validation — TypeScript (zod)
|
||||
|
||||
Validate all required env vars at startup. Exit non-zero on missing values.
|
||||
|
||||
```typescript
|
||||
// src/env.ts
|
||||
import { z } from 'zod';
|
||||
|
||||
const envSchema = z.object({
|
||||
DB_PASSWORD: z.string().min(1, 'DB_PASSWORD is required'),
|
||||
API_KEY: z.string().min(1, 'API_KEY is required'),
|
||||
JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
|
||||
PORT: z.coerce.number().default(3000),
|
||||
NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
|
||||
});
|
||||
|
||||
const result = envSchema.safeParse(process.env);
|
||||
if (!result.success) {
|
||||
console.error('Missing or invalid environment variables:');
|
||||
console.error(result.error.flatten().fieldErrors);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
export const env = result.data;
|
||||
```
|
||||
|
||||
### 4b. App-side schema validation — Python (pydantic)
|
||||
|
||||
```python
|
||||
# src/config.py
|
||||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||||
|
||||
class Settings(BaseSettings):
|
||||
db_password: str
|
||||
api_key: str
|
||||
jwt_secret: str
|
||||
port: int = 3000
|
||||
node_env: str = "production"
|
||||
|
||||
model_config = SettingsConfigDict(env_file=None) # no .env in prod
|
||||
|
||||
try:
|
||||
settings = Settings()
|
||||
except Exception as e:
|
||||
import sys
|
||||
print(f"Missing or invalid environment variables: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
### 4c. App-side schema validation — Go (envconfig)
|
||||
|
||||
```go
|
||||
// config/config.go
|
||||
package config
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/kelseyhightower/envconfig"
|
||||
)
|
||||
|
||||
type Config struct {
|
||||
DBPassword string `envconfig:"DB_PASSWORD" required:"true"`
|
||||
APIKey string `envconfig:"API_KEY" required:"true"`
|
||||
JWTSecret string `envconfig:"JWT_SECRET" required:"true"`
|
||||
Port int `envconfig:"PORT" default:"3000"`
|
||||
}
|
||||
|
||||
func Load() (*Config, error) {
|
||||
var cfg Config
|
||||
if err := envconfig.Process("", &cfg); err != nil {
|
||||
return nil, fmt.Errorf("invalid environment: %w", err)
|
||||
}
|
||||
return &cfg, nil
|
||||
}
|
||||
```
|
||||
|
||||
In your `main.go`:
|
||||
|
||||
```go
|
||||
cfg, err := config.Load()
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Direct-Vault Opt-In Pattern
|
||||
|
||||
Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB rotation with short TTLs, AWS STS, PKI, per-request audit). Document the justification in the project README under "Secrets architecture" before implementing.
|
||||
|
||||
### When it is justified
|
||||
|
||||
- Vault DB secrets engine with lease TTLs shorter than a typical pod lifecycle (< 1 hour)
|
||||
- AWS STS assume-role tokens generated per-request
|
||||
- Vault PKI short-lived certificates (< 24 hours) that must be renewed within a running pod
|
||||
- Per-request audit trail requirement (each app call must appear separately in Vault audit log)
|
||||
|
||||
### Provision an AppRole for the app
|
||||
|
||||
```bash
|
||||
# Enable AppRole auth (if not already enabled)
|
||||
vault auth enable approle
|
||||
|
||||
# Create a Vault policy for the app
|
||||
# Note: KV v2 paths require both the exact path (for the top-level secret) and the
|
||||
# wildcard (for sub-paths). Always include both to avoid permission denied errors.
|
||||
vault policy write <app>-policy - <<EOF
|
||||
path "secret/data/k3s/<app>" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
path "secret/data/k3s/<app>/*" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
path "database/creds/<app>-role" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
EOF
|
||||
|
||||
# Create the AppRole
|
||||
vault write auth/approle/role/<app>-role \
|
||||
token_policies="<app>-policy" \
|
||||
token_ttl=1h \
|
||||
token_max_ttl=4h \
|
||||
secret_id_ttl=0
|
||||
|
||||
# Retrieve role-id and secret-id
|
||||
vault read auth/approle/role/<app>-role/role-id
|
||||
vault write -f auth/approle/role/<app>-role/secret-id
|
||||
```
|
||||
|
||||
### Bootstrap AppRole credentials via ESO (solving the chicken-and-egg problem)
|
||||
|
||||
The AppRole `role-id` and `secret-id` are themselves secrets. Store them in Vault at a bootstrap path, then use ESO to sync them into a k8s Secret. The app reads that k8s Secret at startup to authenticate with Vault directly.
|
||||
|
||||
```bash
|
||||
# Store the bootstrap credentials in Vault
|
||||
vault kv put secret/k3s/<app>-bootstrap \
|
||||
role_id="<role-id>" \
|
||||
secret_id="<secret-id>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy/external-secret-bootstrap.yaml
|
||||
apiVersion: external-secrets.io/v1beta1
|
||||
kind: ExternalSecret
|
||||
metadata:
|
||||
name: <app>-vault-auth
|
||||
namespace: <namespace>
|
||||
spec:
|
||||
refreshInterval: 24h
|
||||
secretStoreRef:
|
||||
name: vault-backend
|
||||
kind: ClusterSecretStore
|
||||
target:
|
||||
name: <app>-vault-auth
|
||||
creationPolicy: Owner
|
||||
data:
|
||||
- secretKey: VAULT_ROLE_ID
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>-bootstrap
|
||||
property: role_id
|
||||
- secretKey: VAULT_SECRET_ID
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>-bootstrap
|
||||
property: secret_id
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy/deployment.yaml (env section for Direct-Vault app)
|
||||
env:
|
||||
- name: VAULT_ADDR
|
||||
value: 'https://vault.example.com' # safe-default: non-secret cluster address
|
||||
- name: VAULT_ROLE_ID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-vault-auth
|
||||
key: VAULT_ROLE_ID
|
||||
- name: VAULT_SECRET_ID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-vault-auth
|
||||
key: VAULT_SECRET_ID
|
||||
```
|
||||
|
||||
### App-side Vault client pattern
|
||||
|
||||
```typescript
|
||||
// src/vault-client.ts — only exists in Direct-Vault apps
|
||||
import vault from 'node-vault';
|
||||
import { z } from 'zod';
|
||||
|
||||
const bootstrapSchema = z.object({
|
||||
VAULT_ADDR: z.string().url(),
|
||||
VAULT_ROLE_ID: z.string().min(1),
|
||||
VAULT_SECRET_ID: z.string().min(1),
|
||||
});
|
||||
|
||||
const bootstrap = bootstrapSchema.parse(process.env);
|
||||
|
||||
const client = vault({ endpoint: bootstrap.VAULT_ADDR });
|
||||
|
||||
export async function getVaultClient() {
|
||||
const { auth } = await client.approleLogin({
|
||||
role_id: bootstrap.VAULT_ROLE_ID,
|
||||
secret_id: bootstrap.VAULT_SECRET_ID,
|
||||
});
|
||||
client.token = auth.client_token;
|
||||
return client;
|
||||
}
|
||||
```
|
||||
|
||||
Document in README under "Secrets architecture": the Vault path, why Direct-Vault is required, and the lease/renewal strategy.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns (CI Lint Targets)
|
||||
|
||||
The following patterns are forbidden in all Mosaic projects. CI lint SHOULD catch these automatically (implementation tracked separately). Agents MUST NOT introduce these patterns.
|
||||
|
||||
### 1. Untagged fallback defaults for required values
|
||||
|
||||
```yaml
|
||||
# FORBIDDEN — required secret with silent fallback
|
||||
environment:
|
||||
- DB_PASSWORD=${DB_PASSWORD:-changeme}
|
||||
- API_KEY=${API_KEY:-}
|
||||
|
||||
# REQUIRED — fast-fail on missing required values
|
||||
environment:
|
||||
- DB_PASSWORD=${DB_PASSWORD:?DB_PASSWORD is required}
|
||||
- API_KEY=${API_KEY:?API_KEY is required}
|
||||
|
||||
# ALLOWED — true convenience default, tagged
|
||||
environment:
|
||||
- PORT=${PORT:-3000} # safe-default: non-secret, app works at any port
|
||||
```
|
||||
|
||||
This applies to: `docker-compose.yml`, k8s manifests, Helm `values.yaml`, any env file committed to git.
|
||||
|
||||
### 2. Vault KV calls in application source code (ESO-default projects)
|
||||
|
||||
```python
|
||||
# FORBIDDEN in ESO-default apps — direct Vault client in app source
|
||||
import hvac
|
||||
client = hvac.Client(url=os.environ['VAULT_ADDR'])
|
||||
secret = client.secrets.kv.v2.read_secret_version(path='myapp/db')
|
||||
```
|
||||
|
||||
ESO-default apps read env vars only. Direct-Vault clients belong only in apps with a documented dynamic-secrets justification in README.
|
||||
|
||||
### 3. Hardcoded secrets or API keys in committed files
|
||||
|
||||
```python
|
||||
# FORBIDDEN — hardcoded credential
|
||||
DB_PASSWORD = "supersecret123"
|
||||
API_KEY = "sk-live-abc123"
|
||||
```
|
||||
|
||||
No exceptions. CI lint must flag any string matching common secret patterns (`password`, `secret`, `api_key`, `token` assigned a literal non-env-var value).
|
||||
|
||||
### 4. `.env` files in production deployment paths
|
||||
|
||||
```
|
||||
# FORBIDDEN — .env file in a production deploy path
|
||||
deploy/.env
|
||||
k8s/.env
|
||||
docker/.env
|
||||
|
||||
# ALLOWED — local dev only
|
||||
.env.example # template only, no real values
|
||||
.env # local dev, must be in .gitignore
|
||||
```
|
||||
|
||||
`.env` files are acceptable in local-dev contexts only and MUST be in `.gitignore`. They are forbidden in any path that a CI pipeline or production deployment process reads directly.
|
||||
|
||||
@@ -50,34 +50,3 @@ export function validateBridgeTyping(input: unknown): asserts input is BridgeTyp
|
||||
assertAgentSlug(o.agent);
|
||||
if (typeof o.typing !== 'boolean') throw new Error('typing must be a boolean');
|
||||
}
|
||||
|
||||
export interface ProvisionRoomDto {
|
||||
name: string;
|
||||
alias?: string;
|
||||
topic?: string;
|
||||
invite?: string[];
|
||||
space_id?: string;
|
||||
}
|
||||
|
||||
export function validateProvisionRoom(input: unknown): asserts input is ProvisionRoomDto {
|
||||
const o = input as Partial<ProvisionRoomDto> | null | undefined;
|
||||
if (!o || typeof o !== 'object') throw new Error('payload must be an object');
|
||||
if (typeof o.name !== 'string' || o.name.length === 0) throw new Error('name is required');
|
||||
if (o.alias !== undefined && (!/^[a-z0-9_.-]+$/.test(o.alias) || o.alias.length > 200)) {
|
||||
throw new Error('alias must match [a-z0-9_.-]+ (max 200 chars)');
|
||||
}
|
||||
if (o.invite !== undefined) {
|
||||
if (
|
||||
!Array.isArray(o.invite) ||
|
||||
o.invite.some((u) => typeof u !== 'string' || !u.startsWith('@'))
|
||||
) {
|
||||
throw new Error('invite must be a list of Matrix user ids');
|
||||
}
|
||||
if (o.invite.length > 50) {
|
||||
throw new Error('invite list exceeds maximum of 50');
|
||||
}
|
||||
}
|
||||
if (o.space_id !== undefined && (typeof o.space_id !== 'string' || !o.space_id.startsWith('!'))) {
|
||||
throw new Error('space_id must be a Matrix room id');
|
||||
}
|
||||
}
|
||||
|
||||
@@ -4,12 +4,8 @@ export { TransactionHandler } from './transactions.js';
|
||||
export type { TransactionHandlerOptions } from './transactions.js';
|
||||
export { buildRegistration, registrationToYaml } from './registration.js';
|
||||
export type { RegistrationOptions } from './registration.js';
|
||||
export {
|
||||
validateBridgeMessage,
|
||||
validateBridgeTyping,
|
||||
validateProvisionRoom,
|
||||
} from './bridge.dto.js';
|
||||
export type { BridgeMessageDto, BridgeTypingDto, ProvisionRoomDto } from './bridge.dto.js';
|
||||
export { validateBridgeMessage, validateBridgeTyping } from './bridge.dto.js';
|
||||
export type { BridgeMessageDto, BridgeTypingDto } from './bridge.dto.js';
|
||||
export type {
|
||||
AppserviceConfig,
|
||||
EventHandler,
|
||||
|
||||
@@ -172,58 +172,6 @@ export class AppserviceIntent {
|
||||
});
|
||||
}
|
||||
|
||||
/** Create a room as the AS sender: agents get PL 50 by namespace via the
|
||||
* sender (PL 100); humans invited at default PL. Optionally link into a
|
||||
* space (m.space.child + m.space.parent). Returns the room id. */
|
||||
async createRoom(options: {
|
||||
name: string;
|
||||
alias?: string;
|
||||
topic?: string;
|
||||
invite?: string[];
|
||||
spaceId?: string;
|
||||
}): Promise<{ roomId: string; spaceLinked: boolean; spaceError?: string }> {
|
||||
const body: Record<string, unknown> = {
|
||||
name: options.name,
|
||||
preset: 'private_chat',
|
||||
invite: options.invite ?? [],
|
||||
power_level_content_override: {
|
||||
users: { [this.senderUserId]: 100 },
|
||||
// state_default 50 stays; the AS sender can grant agents as needed.
|
||||
},
|
||||
};
|
||||
if (options.alias) body.room_alias_name = options.alias;
|
||||
if (options.topic) body.topic = options.topic;
|
||||
const res = await this.request('POST', '/_matrix/client/v3/createRoom', {
|
||||
userId: this.senderUserId,
|
||||
body,
|
||||
});
|
||||
const roomId = res.room_id;
|
||||
if (typeof roomId !== 'string') throw new Error('createRoom returned no room_id');
|
||||
if (!options.spaceId) {
|
||||
return { roomId, spaceLinked: false };
|
||||
}
|
||||
// Space-link failures must NOT throw: the room already exists, and an
|
||||
// exception would hide the room_id (orphaned room, no recovery path).
|
||||
const encodedSpaceId = encodeURIComponent(options.spaceId);
|
||||
const encodedRoomId = encodeURIComponent(roomId);
|
||||
try {
|
||||
await this.request(
|
||||
'PUT',
|
||||
`/_matrix/client/v3/rooms/${encodedSpaceId}/state/m.space.child/${encodedRoomId}`,
|
||||
{ userId: this.senderUserId, body: { via: [this.cfg.domain], suggested: true } },
|
||||
);
|
||||
await this.request(
|
||||
'PUT',
|
||||
`/_matrix/client/v3/rooms/${encodedRoomId}/state/m.space.parent/${encodedSpaceId}`,
|
||||
{ userId: this.senderUserId, body: { via: [this.cfg.domain], canonical: true } },
|
||||
);
|
||||
} catch (error) {
|
||||
const message = error instanceof Error ? error.message : String(error);
|
||||
return { roomId, spaceLinked: false, spaceError: message };
|
||||
}
|
||||
return { roomId, spaceLinked: true };
|
||||
}
|
||||
|
||||
/** Set display name for an agent's virtual user. */
|
||||
async setDisplayName(agent: string, displayName: string): Promise<void> {
|
||||
const userId = await this.ensureRegistered(agent);
|
||||
|
||||
@@ -34,7 +34,6 @@ At session start, additionally:
|
||||
10. Manual `docker build` / `docker push` for deployment is FORBIDDEN when CI/CD pipelines exist in the repository. CI is the ONLY canonical build path for container images.
|
||||
11. Before ANY build or deployment action, you MUST check for existing CI/CD pipeline configuration (`.woodpecker/`, `.woodpecker.yml`, `.github/workflows/`, etc.). If pipelines exist, use them — do not build locally.
|
||||
12. The mandatory intake procedure is NOT conditional on perceived task complexity. A "simple" commit-push-deploy task has the same procedural requirements as a multi-file feature. Skipping intake because a task "seems simple" is the most common framework violation.
|
||||
13. **Merge authority (coordinated work):** when a coordinator/orchestrator session is active for the work, the post-review MERGE GO-AHEAD is the coordinator's to give — once code has passed the required review gates, request the coordinator's go-ahead and merge on their confirmation; do NOT wait on the human owner personally. Solo (uncoordinated) delivery keeps the default: merge without routine confirmation per gates 2 and 9. A "No self-merge" note on a PR means no UNREVIEWED self-merge — it does not suspend coordinator-authorized merges. (Policy: Jason, 2026-06-11.)
|
||||
|
||||
## Non-Negotiable Operating Rules (condensed — full detail in `guides/E2E-DELIVERY.md`)
|
||||
|
||||
|
||||
@@ -27,16 +27,6 @@ Master/slave model:
|
||||
- Do not perform destructive git/file actions without explicit instruction.
|
||||
- Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.
|
||||
|
||||
### Secrets handling (HARD RULE)
|
||||
|
||||
- Vault is the canonical source-of-truth for every secret in every environment. No exceptions.
|
||||
- For k8s workloads, the default read path is **External Secrets Operator → k8s Secret → env var** (`secretKeyRef`). The app reads standard env vars; no Vault client in app code.
|
||||
- Direct-Vault clients in application code are **opt-in only**, justified per-app by a documented dynamic-secrets requirement (e.g., DB rotation, AWS STS). Default to ESO. Document the justification in the project's README under "Secrets architecture".
|
||||
- `${VAR:-default}` fallback syntax in any deployment configuration (compose, k8s manifests, Helm values, env files committed to git) is **forbidden** for required values. Use `${VAR:?VAR is required}` to fast-fail. Defaults are allowed only for true conveniences (e.g. `${PORT:-3000}`) and MUST be tagged `# safe-default: <reason>` so a reviewer can confirm the intent.
|
||||
- `.env` files in production deployment paths are **forbidden**. `.env.example` and `.env` in local-dev paths are fine.
|
||||
- App startup MUST validate required secrets against a schema (zod / pydantic / equivalent) and exit non-zero on missing required values. Never run with defaulted weak fallbacks.
|
||||
- New apps: bootstrap checklist (see `~/.config/mosaic/guides/BOOTSTRAP.md`) MUST include Vault path provisioning + `ExternalSecret` manifest + README declaring the Vault path and required keys.
|
||||
|
||||
## Session Lifecycle Contract
|
||||
|
||||
- Start: `scripts/agent/session-start.sh`
|
||||
|
||||
@@ -453,26 +453,6 @@ Initialize standard labels and the first pre-MVP milestone:
|
||||
|
||||
---
|
||||
|
||||
## Secrets Bootstrap (Required for Every New App)
|
||||
|
||||
Every new application MUST complete the following secrets bootstrap before deploying to any non-local environment. This is a hard gate — deployment without completed secrets bootstrap is forbidden.
|
||||
|
||||
### Secrets bootstrap checklist
|
||||
|
||||
- [ ] Vault path created: `vault kv put secret/k3s/<app>/ ...` with all required secret fields
|
||||
- [ ] Required secrets listed in project README under a "Secrets architecture" section, including:
|
||||
- Vault path(s) used
|
||||
- All required secret keys and their purpose
|
||||
- Whether the app uses ESO bridge (default) or Direct-Vault (opt-in, with justification)
|
||||
- [ ] `external-secret.yaml` manifest committed to repo's `deploy/` or `k8s/` directory
|
||||
- [ ] Deployment YAML references the synced k8s Secret via `secretKeyRef` (not raw env vars or `.env` files)
|
||||
- [ ] App startup has schema-based validation for all required env vars (zod / pydantic / envconfig equivalent) that exits non-zero on missing required values
|
||||
- [ ] Direct-Vault opt-in (if applicable): justification documented in README + AppRole provisioned + bootstrap credentials stored in Vault and synced via a separate `ExternalSecret`
|
||||
|
||||
See `~/.config/mosaic/guides/VAULT-SECRETS.md` for full worked examples of the ESO bridge pattern, the Direct-Vault opt-in pattern, and the forbidden antipatterns.
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
After bootstrapping, verify:
|
||||
|
||||
@@ -88,11 +88,6 @@ For implementation work, you MUST run this cycle in order:
|
||||
|
||||
### Post-PR Hard Gate (Execute Sequentially, No Exceptions)
|
||||
|
||||
> **Merge authority:** if a coordinator/orchestrator session is active for this
|
||||
> work, obtain the coordinator's merge go-ahead after review passes, then run
|
||||
> the gate (AGENTS.md hard gate "Merge authority"). Solo delivery proceeds
|
||||
> without asking.
|
||||
|
||||
1. `~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose merge -B main`
|
||||
2. `~/.config/mosaic/tools/git/pr-merge.sh -n <PR_NUMBER> -m squash`
|
||||
3. `~/.config/mosaic/tools/git/pr-ci-wait.sh -n <PR_NUMBER>`
|
||||
|
||||
@@ -203,374 +203,3 @@ Error: token expired
|
||||
3. **Audit logging** - All access is logged; act accordingly
|
||||
4. **No local copies** - Don't store secrets in files or env vars long-term
|
||||
5. **Rotate on compromise** - Immediately rotate any exposed secrets
|
||||
|
||||
---
|
||||
|
||||
## Secrets Architecture Decision Matrix
|
||||
|
||||
Use this table to choose between the ESO bridge (default) and Direct-Vault (opt-in) patterns for every new app or integration.
|
||||
|
||||
| Factor | ESO Bridge (default) | Direct-Vault (opt-in) |
|
||||
| --------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Use-case** | All static secrets (DB creds, API keys, signing keys, OAuth secrets) | Dynamic creds with short TTLs (DB rotation, AWS STS, PKI), per-request audit trails, or lease renewal mid-pod-lifecycle |
|
||||
| **App code change** | None — reads standard env vars via `secretKeyRef` | Requires Vault client (`hvac`, `node-vault`, `vault/api`) in application code |
|
||||
| **Secret rotation** | ESO re-syncs on Vault write; pod restart or secret refresh picks up new value | App manages lease renewal or re-auth within the running process |
|
||||
| **Audit granularity** | Access logged at Vault when ESO syncs; no per-request app audit | Every app request to Vault is a separate audit log entry |
|
||||
| **Operational burden** | Low — ESO handles polling, sync, and k8s Secret lifecycle | Higher — app must handle auth, lease renewal, error paths, and token rotation |
|
||||
| **Justification required?** | No — this is the default | Yes — document in project README under "Secrets architecture" |
|
||||
| **Example use cases** | Web app DB password, OAuth client secret, JWT signing key, API token | HashiCorp DB secrets engine with 15-min TTL leases, AWS STS assume-role, Vault PKI short-lived certs |
|
||||
|
||||
**Decision rule:** If you are unsure, use ESO. Only justify Direct-Vault when the secret cannot be safely stored in a k8s Secret (too short-lived, per-request TTL required, or mid-lifecycle renewal needed).
|
||||
|
||||
---
|
||||
|
||||
## ESO Bridge Pattern (Default)
|
||||
|
||||
This is the required default for all k8s workloads. Follow this exact pattern unless a documented dynamic-secrets requirement justifies Direct-Vault.
|
||||
|
||||
### 1. Provision Vault path
|
||||
|
||||
```bash
|
||||
# Write the secrets for the app (run once; use IaC/Terraform for repeatable provisioning)
|
||||
vault kv put secret/k3s/<app> \
|
||||
db_password="..." \
|
||||
api_key="..." \
|
||||
jwt_secret="..."
|
||||
```
|
||||
|
||||
Use the canonical path structure: `secret/k3s/<app>` for k3s cluster workloads.
|
||||
|
||||
### 2. ExternalSecret manifest
|
||||
|
||||
Commit this to the repo's `deploy/` or `k8s/` directory:
|
||||
|
||||
```yaml
|
||||
# deploy/external-secret.yaml
|
||||
apiVersion: external-secrets.io/v1beta1
|
||||
kind: ExternalSecret
|
||||
metadata:
|
||||
name: <app>-secrets
|
||||
namespace: <namespace>
|
||||
spec:
|
||||
refreshInterval: 1h
|
||||
secretStoreRef:
|
||||
name: vault-backend # ClusterSecretStore name — verify with cluster admin
|
||||
kind: ClusterSecretStore
|
||||
target:
|
||||
name: <app>-secrets # k8s Secret name that will be created
|
||||
creationPolicy: Owner
|
||||
data:
|
||||
- secretKey: DB_PASSWORD # key in the k8s Secret
|
||||
remoteRef:
|
||||
key: secret/k3s/<app> # Vault path
|
||||
property: db_password # field within the Vault secret
|
||||
- secretKey: API_KEY
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>
|
||||
property: api_key
|
||||
- secretKey: JWT_SECRET
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>
|
||||
property: jwt_secret
|
||||
```
|
||||
|
||||
### 3. Deployment manifest — reference synced k8s Secret
|
||||
|
||||
```yaml
|
||||
# deploy/deployment.yaml (env section)
|
||||
env:
|
||||
- name: DB_PASSWORD
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets # matches ExternalSecret target.name
|
||||
key: DB_PASSWORD
|
||||
- name: API_KEY
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets
|
||||
key: API_KEY
|
||||
- name: JWT_SECRET
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-secrets
|
||||
key: JWT_SECRET
|
||||
- name: PORT
|
||||
value: '3000' # safe-default: non-secret, no Vault needed
|
||||
```
|
||||
|
||||
### 4. App-side schema validation — TypeScript (zod)
|
||||
|
||||
Validate all required env vars at startup. Exit non-zero on missing values.
|
||||
|
||||
```typescript
|
||||
// src/env.ts
|
||||
import { z } from 'zod';
|
||||
|
||||
const envSchema = z.object({
|
||||
DB_PASSWORD: z.string().min(1, 'DB_PASSWORD is required'),
|
||||
API_KEY: z.string().min(1, 'API_KEY is required'),
|
||||
JWT_SECRET: z.string().min(32, 'JWT_SECRET must be at least 32 chars'),
|
||||
PORT: z.coerce.number().default(3000),
|
||||
NODE_ENV: z.enum(['development', 'production', 'test']).default('production'),
|
||||
});
|
||||
|
||||
const result = envSchema.safeParse(process.env);
|
||||
if (!result.success) {
|
||||
console.error('Missing or invalid environment variables:');
|
||||
console.error(result.error.flatten().fieldErrors);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
export const env = result.data;
|
||||
```
|
||||
|
||||
### 4b. App-side schema validation — Python (pydantic)
|
||||
|
||||
```python
|
||||
# src/config.py
|
||||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||||
|
||||
class Settings(BaseSettings):
|
||||
db_password: str
|
||||
api_key: str
|
||||
jwt_secret: str
|
||||
port: int = 3000
|
||||
node_env: str = "production"
|
||||
|
||||
model_config = SettingsConfigDict(env_file=None) # no .env in prod
|
||||
|
||||
try:
|
||||
settings = Settings()
|
||||
except Exception as e:
|
||||
import sys
|
||||
print(f"Missing or invalid environment variables: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
### 4c. App-side schema validation — Go (envconfig)
|
||||
|
||||
```go
|
||||
// config/config.go
|
||||
package config
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/kelseyhightower/envconfig"
|
||||
)
|
||||
|
||||
type Config struct {
|
||||
DBPassword string `envconfig:"DB_PASSWORD" required:"true"`
|
||||
APIKey string `envconfig:"API_KEY" required:"true"`
|
||||
JWTSecret string `envconfig:"JWT_SECRET" required:"true"`
|
||||
Port int `envconfig:"PORT" default:"3000"`
|
||||
}
|
||||
|
||||
func Load() (*Config, error) {
|
||||
var cfg Config
|
||||
if err := envconfig.Process("", &cfg); err != nil {
|
||||
return nil, fmt.Errorf("invalid environment: %w", err)
|
||||
}
|
||||
return &cfg, nil
|
||||
}
|
||||
```
|
||||
|
||||
In your `main.go`:
|
||||
|
||||
```go
|
||||
cfg, err := config.Load()
|
||||
if err != nil {
|
||||
fmt.Fprintln(os.Stderr, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Direct-Vault Opt-In Pattern
|
||||
|
||||
Use this pattern ONLY when a documented dynamic-secrets requirement applies (DB rotation with short TTLs, AWS STS, PKI, per-request audit). Document the justification in the project README under "Secrets architecture" before implementing.
|
||||
|
||||
### When it is justified
|
||||
|
||||
- Vault DB secrets engine with lease TTLs shorter than a typical pod lifecycle (< 1 hour)
|
||||
- AWS STS assume-role tokens generated per-request
|
||||
- Vault PKI short-lived certificates (< 24 hours) that must be renewed within a running pod
|
||||
- Per-request audit trail requirement (each app call must appear separately in Vault audit log)
|
||||
|
||||
### Provision an AppRole for the app
|
||||
|
||||
```bash
|
||||
# Enable AppRole auth (if not already enabled)
|
||||
vault auth enable approle
|
||||
|
||||
# Create a Vault policy for the app
|
||||
# Note: KV v2 paths require both the exact path (for the top-level secret) and the
|
||||
# wildcard (for sub-paths). Always include both to avoid permission denied errors.
|
||||
vault policy write <app>-policy - <<EOF
|
||||
path "secret/data/k3s/<app>" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
path "secret/data/k3s/<app>/*" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
path "database/creds/<app>-role" {
|
||||
capabilities = ["read"]
|
||||
}
|
||||
EOF
|
||||
|
||||
# Create the AppRole
|
||||
vault write auth/approle/role/<app>-role \
|
||||
token_policies="<app>-policy" \
|
||||
token_ttl=1h \
|
||||
token_max_ttl=4h \
|
||||
secret_id_ttl=0
|
||||
|
||||
# Retrieve role-id and secret-id
|
||||
vault read auth/approle/role/<app>-role/role-id
|
||||
vault write -f auth/approle/role/<app>-role/secret-id
|
||||
```
|
||||
|
||||
### Bootstrap AppRole credentials via ESO (solving the chicken-and-egg problem)
|
||||
|
||||
The AppRole `role-id` and `secret-id` are themselves secrets. Store them in Vault at a bootstrap path, then use ESO to sync them into a k8s Secret. The app reads that k8s Secret at startup to authenticate with Vault directly.
|
||||
|
||||
```bash
|
||||
# Store the bootstrap credentials in Vault
|
||||
vault kv put secret/k3s/<app>-bootstrap \
|
||||
role_id="<role-id>" \
|
||||
secret_id="<secret-id>"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy/external-secret-bootstrap.yaml
|
||||
apiVersion: external-secrets.io/v1beta1
|
||||
kind: ExternalSecret
|
||||
metadata:
|
||||
name: <app>-vault-auth
|
||||
namespace: <namespace>
|
||||
spec:
|
||||
refreshInterval: 24h
|
||||
secretStoreRef:
|
||||
name: vault-backend
|
||||
kind: ClusterSecretStore
|
||||
target:
|
||||
name: <app>-vault-auth
|
||||
creationPolicy: Owner
|
||||
data:
|
||||
- secretKey: VAULT_ROLE_ID
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>-bootstrap
|
||||
property: role_id
|
||||
- secretKey: VAULT_SECRET_ID
|
||||
remoteRef:
|
||||
key: secret/k3s/<app>-bootstrap
|
||||
property: secret_id
|
||||
```
|
||||
|
||||
```yaml
|
||||
# deploy/deployment.yaml (env section for Direct-Vault app)
|
||||
env:
|
||||
- name: VAULT_ADDR
|
||||
value: 'https://vault.example.com' # safe-default: non-secret cluster address
|
||||
- name: VAULT_ROLE_ID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-vault-auth
|
||||
key: VAULT_ROLE_ID
|
||||
- name: VAULT_SECRET_ID
|
||||
valueFrom:
|
||||
secretKeyRef:
|
||||
name: <app>-vault-auth
|
||||
key: VAULT_SECRET_ID
|
||||
```
|
||||
|
||||
### App-side Vault client pattern
|
||||
|
||||
```typescript
|
||||
// src/vault-client.ts — only exists in Direct-Vault apps
|
||||
import vault from 'node-vault';
|
||||
import { z } from 'zod';
|
||||
|
||||
const bootstrapSchema = z.object({
|
||||
VAULT_ADDR: z.string().url(),
|
||||
VAULT_ROLE_ID: z.string().min(1),
|
||||
VAULT_SECRET_ID: z.string().min(1),
|
||||
});
|
||||
|
||||
const bootstrap = bootstrapSchema.parse(process.env);
|
||||
|
||||
const client = vault({ endpoint: bootstrap.VAULT_ADDR });
|
||||
|
||||
export async function getVaultClient() {
|
||||
const { auth } = await client.approleLogin({
|
||||
role_id: bootstrap.VAULT_ROLE_ID,
|
||||
secret_id: bootstrap.VAULT_SECRET_ID,
|
||||
});
|
||||
client.token = auth.client_token;
|
||||
return client;
|
||||
}
|
||||
```
|
||||
|
||||
Document in README under "Secrets architecture": the Vault path, why Direct-Vault is required, and the lease/renewal strategy.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden Patterns (CI Lint Targets)
|
||||
|
||||
The following patterns are forbidden in all Mosaic projects. CI lint SHOULD catch these automatically (implementation tracked separately). Agents MUST NOT introduce these patterns.
|
||||
|
||||
### 1. Untagged fallback defaults for required values
|
||||
|
||||
```yaml
|
||||
# FORBIDDEN — required secret with silent fallback
|
||||
environment:
|
||||
- DB_PASSWORD=${DB_PASSWORD:-changeme}
|
||||
- API_KEY=${API_KEY:-}
|
||||
|
||||
# REQUIRED — fast-fail on missing required values
|
||||
environment:
|
||||
- DB_PASSWORD=${DB_PASSWORD:?DB_PASSWORD is required}
|
||||
- API_KEY=${API_KEY:?API_KEY is required}
|
||||
|
||||
# ALLOWED — true convenience default, tagged
|
||||
environment:
|
||||
- PORT=${PORT:-3000} # safe-default: non-secret, app works at any port
|
||||
```
|
||||
|
||||
This applies to: `docker-compose.yml`, k8s manifests, Helm `values.yaml`, any env file committed to git.
|
||||
|
||||
### 2. Vault KV calls in application source code (ESO-default projects)
|
||||
|
||||
```python
|
||||
# FORBIDDEN in ESO-default apps — direct Vault client in app source
|
||||
import hvac
|
||||
client = hvac.Client(url=os.environ['VAULT_ADDR'])
|
||||
secret = client.secrets.kv.v2.read_secret_version(path='myapp/db')
|
||||
```
|
||||
|
||||
ESO-default apps read env vars only. Direct-Vault clients belong only in apps with a documented dynamic-secrets justification in README.
|
||||
|
||||
### 3. Hardcoded secrets or API keys in committed files
|
||||
|
||||
```python
|
||||
# FORBIDDEN — hardcoded credential
|
||||
DB_PASSWORD = "supersecret123"
|
||||
API_KEY = "sk-live-abc123"
|
||||
```
|
||||
|
||||
No exceptions. CI lint must flag any string matching common secret patterns (`password`, `secret`, `api_key`, `token` assigned a literal non-env-var value).
|
||||
|
||||
### 4. `.env` files in production deployment paths
|
||||
|
||||
```
|
||||
# FORBIDDEN — .env file in a production deploy path
|
||||
deploy/.env
|
||||
k8s/.env
|
||||
docker/.env
|
||||
|
||||
# ALLOWED — local dev only
|
||||
.env.example # template only, no real values
|
||||
.env # local dev, must be in .gitignore
|
||||
```
|
||||
|
||||
`.env` files are acceptable in local-dev contexts only and MUST be in `.gitignore`. They are forbidden in any path that a CI pipeline or production deployment process reads directly.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@mosaicstack/mosaic",
|
||||
"version": "0.0.31",
|
||||
"version": "0.0.30",
|
||||
"repository": {
|
||||
"type": "git",
|
||||
"url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
|
||||
|
||||
Reference in New Issue
Block a user