# archipelago **The archie-core marketplace.** One directory per extension surface; each surface directory holds one subdirectory per extension. An extension ships as a package: a `package.yaml` plus its Go source or data files. ## Layout ``` secret-engines// package.yaml + Go source, served over secretengine.v1 workflows// package.yaml + workflow YAML, projected into workflow-definitions channels// package.yaml + Go source, served over channel.v1 (email) forge// package.yaml + Go source, served over forge.v1 (github, gitea) connectors// package.yaml + Go source, served over connector.v1 (alertmanager) guards// package.yaml + Go source, served over guard.v1 (business-hours, integrity, policy, confidence) playbooks// package.yaml + EDA playbook YAML, projected into eda-playbooks profiles// package.yaml + agent profile YAML, projected into agent-profiles sdk/ generated surface stubs and the Serve helper scripts/pack.sh build one package and push it to a registry scripts/publish.sh pack every package and publish the signed catalogue ``` A surface's contract is the gRPC service in archie-core's `proto//v1`. Regenerate `sdk/` from it with `buf generate ../archie-core/proto --path ../archie-core/proto/` (see [buf.gen.yaml](buf.gen.yaml)). An extension can be written in any language; the Go SDK in [sdk/](sdk) is a convenience. ## Safety An extension runs with the operator's accounts and talks to the outside world, so every one of them holds to these before it ships: - **Inbound is authenticated before it is acted on.** Identity comes only from something the extension or a trusted upstream verified (a provider's DMARC/DKIM result, a host-verified webhook signature), never from a field the sender writes. Unauthenticated input is dropped. - **Protocols come from maintained libraries** (go-imap, go-smtp, go-github, the Gitea SDK). No hand-written protocol code. - **No listening ports.** An extension dials out; inbound reaches it through the host. - **Operator data outside the extension's job is left untouched.** It changes only what it acted on (the email channel marks only routed mail read). - **Authority is declared in package.yaml** (env, egress hosts), and nothing else is assumed. Input that reaches a CLI is validated so it cannot become a flag. - **The security check has a table test** covering forged and wrong-party input. ## Publish and install Every push to `main` packs each package to `git.catlow.cloud/sam/archipelago` and publishes the catalogue that lists them, signed with the `ARCHIPELAGO_CATALOGUE_KEY` secret. archie-core trusts that catalogue's key, so its Extensions page lists every package with an Install button. For a package under development, pack it to a local registry and install it by reference: ``` scripts/pack.sh secret-engines/bws localhost:5001/bws:1.0.0 # prints the digest ``` Then accept the authority the package declares, and enable it. An extension runs only while all three hold. A data package (no `main.go`) needs only the install: its files are projected into the matching resource and withdrawn when the package is removed. Platform: linux/amd64. ## Docs and entry points - Example package for each surface: [workflow](workflows/firewall/package.yaml), [channel](channels/email/package.yaml), [forge](forge/gitea/package.yaml), [secret engine](secret-engines/bws/package.yaml), [playbook](playbooks/bug-tdd/package.yaml), [profile](profiles/network-investigator/package.yaml) - Pack one package or publish the signed catalogue: [scripts/pack.sh](scripts/pack.sh), [scripts/publish.sh](scripts/publish.sh)