Release forge 0.2.4 with scoped local OAuth and retained custody

.dockerignore

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 .git
 .venv
 .forge

.gitattributes

@@ -1 +1,2 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 studio/public/licenses/markdown-LICENSES.txt whitespace=-blank-at-eof

.github/workflows/ci.yml

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 name: Verify
 on:
   push:

.github/workflows/docs.yml

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 name: Documentation
 on:
   push:

.github/workflows/release.yml

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 name: Release
 on:
   push:

.gitignore

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 .venv/
 .forge/
 .env

.prettierignore

@@ -1,2 +1,3 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 # Preserve checksummed licensed framework knowledge sources.
 src/firefly_forge/resources/knowledge/

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Changelog
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 ## 0.1.0 — 2026-10-11
 
 - Introduce the Firefly Forge software factory, PyFly control plane and web Studio.

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 Open an issue describing the behavior and how to reproduce it. Keep changes focused and match existing conventions. Use Python 3.13+, Node.js 22+ and Git.
 
 ```sh

Dockerfile

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 FROM node:22-bookworm-slim AS studio
 WORKDIR /build/studio
 COPY studio/package*.json ./

Makefile

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 .PHONY: check python-check studio-check docs docs-check docs-pages-check package serve
 
 check: python-check studio-check docs-check

README.md

@@ -1,5 +1,7 @@
 # firefly forge
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 ![firefly forge: from brief to verified software](assets/banner.svg)
 
 firefly forge is the Firefly software factory. Describe a product's users, journeys and acceptance checks, connect its repositories, then choose a stack and coding provider. Review the implementation, actual checks and retained evidence before publishing a pull request.

SECURITY.md

@@ -1,7 +1,17 @@
 # Security
 
-Report vulnerabilities privately through GitHub Security Advisories for this repository. Include the affected release, a reproduction and the expected trust boundary. Do not publish working credentials or sensitive customer source.
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
-Forge 0.1 is a single-operator development factory. A token grants access to repository source, generated code, worker commands and publication. Run it on a dedicated trusted development host, bind to loopback, and use TLS/access controls when exposing it remotely. CLI sandboxes and confined Agentic file tools do not constitute a multi-tenant operating-system sandbox for verification commands. Never connect an untrusted repository to a host holding unrelated production credentials.
+Report vulnerabilities privately through GitHub Security Advisories for this repository. Include the affected release, a reproduction with synthetic data and the expected trust boundary. Exclude working credentials, private logs and sensitive customer source.
 
-Secrets use environment configuration and Git credential helpers. Generated artifacts exclude private paths. Interrupted runs require an explicit retry. Pull-request publication requires passing verification; Forge never merges generated changes.
+firefly forge is a software factory with native pyfly authentication, project permissions, PostgreSQL persistence and one execution leader. Shared installations use Keycloak OIDC, an exact API audience and protected server sessions. Explicit local bootstrap is restricted to its configured loopback mode. Current identity, project and repository authority must permit execution and later effects; a queued request does not renew that authority.
+
+Host coding and verification execute with the service account's filesystem and process access and require current administrator authority. Project users need an available isolated runner. Use a dedicated service identity and private retained storage. Confined file tools and a coding CLI's permission controls do not establish operating-system isolation for the complete factory. Keep unrelated production credentials and host sockets out of project execution environments.
+
+Owner-private configuration files and immutable credential revisions protect selected service secrets through filesystem permissions. Connection OAuth credentials are separately encrypted in PostgreSQL under the installation's shared encryption key. Browser consent, token exchange, refresh and scoped resource use have retained policy, actor, project and effect checks. Unknown provider responses require reconciliation. Local disconnect stops factory use and erases active tokens; provider-side authorization must be revoked separately.
+
+The implemented local OAuth service requires explicit development settings, different literal factory/provider hosts and its fixed read-only resource. Vendor OAuth templates remain inactive until their provider contracts and scoped adapters are admitted. Schema discovery, exact review and repository/tool grants remain mandatory even after consent. Current authorization also applies when returning cached tool receipts.
+
+Write-ahead intents and receipts retain execution evidence. A database rollback, restart or timeout cannot establish that an external effect did not happen. Observe the exact remote outcome before another publication, deployment or knowledge write. Passing checks and matching source evidence precede delivery; forge does not merge generated changes automatically.
+
+Keep factory PostgreSQL, private credential revisions, source workspaces, flycanon data and original objects in a consistent backup. Test restoration and unresolved-effect recovery in an isolated installation. Production cluster isolation, live vendor integrations and generated-product deployment need their own acceptance evidence. See the [security guide](docs/security.md) and [factory infrastructure guide](docs/factory-infrastructure.md).

compose.yaml

@@ -1,3 +1,4 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
 services:
   forge:
     build: .

docs/agent-integrations.md

@@ -4,6 +4,8 @@ description: Operate forge through the Python SDK, CLI and MCP with authenticate
 
 # Operate products from Python, the CLI or MCP
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 The Python client, CLI and MCP tools call the same authenticated factory API. Project operations, source inspections, product conversations and worker questions use the factory's permissions, revisions and durable receipts. The clients use the running factory and its execution lease.
 
 Set `FORGE_URL` to the running factory and provide `FORGE_API_TOKEN` through your operator environment. Source-control credentials remain in the factory's application or OAuth configuration; do not put the operator token in an issue comment or product brief.

docs/agent-lifecycle.md

@@ -4,6 +4,8 @@ description: Inspect participants, skills, knowledge access and handoffs through
 
 # Agent lifecycle
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 Use **Agents & skills** to follow work from a product decision through source delivery and application operation. The lifecycle catalog distinguishes AI dialogue, a run-selected coding provider, and deterministic services. A participant describes an implemented service or instruction binding; it is not evidence that a model session or external action has occurred.
 
 <picture>

docs/agent-roles.md

@@ -4,6 +4,8 @@ description: Configure factory roles and community skill instructions, with expl
 
 # Factory roles and community skills
 
+<!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
+
 A role assigns responsibility to an actual factory stage. It does not create a separate model session. The default implementation uses one selected coding provider, deterministic planning and source checks, real repository verification, and an optional explicitly configured assurance reviewer.
 
 ## Responsibilities and execution

docs/api.md

@@ -169,4 +169,4 @@ Provider configuration accepts `{"values":{"model":"MODEL","api_key":"PRIVATE_KE
 
 Project policies accept `{"skills":["implementation","verification","security"]}`. Omitting `skills` when creating a run uses project defaults; an explicit empty array selects no optional policies. Core framework integration, source safety and verification cannot be disabled.
 
-See [SCM](scm.md) for repository discovery, OAuth redirects and grants; [knowledge](knowledge.md) for source selection and project scopes; and [deployment](deployment.md) for target commands, source checks and rollback requests.
+See [connected accounts](connected-accounts.md#api-and-client-contract) for typed service policy, client registration, browser consent and effect receipts; [SCM](scm.md) for repository discovery, OAuth redirects and grants; [knowledge](knowledge.md) for source selection and project scopes; and [deployment](deployment.md) for target commands, source checks and rollback requests.

docs/architecture.md

@@ -22,7 +22,7 @@ The factory itself uses [pyfly](https://fireflyframework.org/frameworks/python/)
 <figcaption>The same services support a combined process and split admission/execution. Read the arrows as responsibility boundaries; coding providers, Git and knowledge services produce effects outside a database transaction.</figcaption>
 </figure>
 
-`create_runtime()` constructs the native `PyFlyApplication`, registers `ForgeBeans` and the typed controllers/repositories, then lets the container inject their dependencies. `create_application()` adds the Starlette adapter, request limits, trusted-host middleware and Studio's static build. The worker uses the runtime without an HTTP listener.
+`create_runtime()` constructs the native `PyFlyApplication`, registers `FactoryConfiguration` and the typed controllers/repositories, then resolves their registered dependencies through the container. Domain services also retain explicit collaborators and test seams; this does not establish that every construction path is container-owned. `create_application()` adds the Starlette adapter, request limits, trusted-host middleware and Studio's static build. The worker uses the runtime without an HTTP listener.
 
 | Layer | Concrete implementation | Contract |
 | --- | --- | --- |
@@ -35,7 +35,36 @@ The factory itself uses [pyfly](https://fireflyframework.org/frameworks/python/)
 
 Lifecycle ordering initializes `Store` before topology and execution consumers. The engine acquires ownership before recovering retained work. Worker supervision watches coding, delivery, deployment, campaign, channel and application-observation consumers. A stopped required consumer degrades execution readiness; shutdown closes dispatch and drains effects before releasing ownership. See [runtime roles](runtime-roles.md).
 
-Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/api.py) (`ForgeBeans`, `create_runtime`, `create_application`), [`worker_runtime.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/worker_runtime.py) (`WorkerSupervision`).
+### Native knowledge services
+
+`FactoryConfiguration.knowledge_connection()` injects the private `ConfigurationStore` into `KnowledgeConnection`. `knowledge_manager()` injects `Store`, `Engine`, `Journal`, that connection and `KnowledgeFirst`; it connects the same manager to execution and native knowledge-first tools. `KnowledgeController` uses typed pyfly mappings for configuration, authentication tests, scoped search, source indexing and verified memory. `KnowledgeUploads` has its own injected repository for retained source-upload evidence.
+
+The connection owns authenticated SDK transport and TLS trust. The manager chooses the frozen connection revision, confines repository scope and handles source/canonical receipts. `KnowledgeFirst` combines those cited references with eligible PostgreSQL procedure outcomes before considering configured web search. It cannot treat a search hit as an approved procedure.
+
+Flycanon's server runs in a separate environment, with its own migration and ingestion worker. Installing the Python SDK into forge supplies the client; the managed server image installs the released server independently. No flyquery bean, controller, client dependency or analytics worker is registered in this runtime.
+
+Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/api.py) (`FactoryConfiguration`, `create_runtime`, `create_application`), [`worker_runtime.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/worker_runtime.py) (`WorkerSupervision`).
+
+### Connection OAuth and resource custody
+
+`FactoryConfiguration` registers `OAuthProviderPolicies`, `ConnectionOAuth`, `OAuthResources` and the external MCP registry as separate native beans. Policy admission fixes the issuer, endpoints, resource and scope. The connection service binds client registration and browser attempts to the current actor and immutable revision; it uses public pyfly OAuth client and PKCE APIs. PostgreSQL stores encrypted credentials, grant families, effects and append-only events.
+
+`OAuthResources` signs a project/resource binding and rechecks current policy, registration, grant family/revision, expiry and project authority before dispatch. A schema review and exact repository/tool grant remain mandatory. Current authorization also protects cached broker receipts: a completed result cannot bypass a withdrawn policy or revoked grant.
+
+<figure class="forge-shot forge-architecture-diagram" markdown="1">
+<picture>
+  <source media="(max-width: 640px)" srcset="../diagrams/architecture-oauth-narrow.svg">
+  <img src="../diagrams/architecture-oauth.svg" alt="Admit a fixed service, retain client registration, authorize in the browser, record token effects, bind the exact project resource, and review schemas and tool grants before broker dispatch.">
+</picture>
+
+[Open full diagram](diagrams/architecture-oauth.svg) · [Portrait layout](diagrams/architecture-oauth-narrow.svg)
+
+<figcaption>Consent retains an account grant. Current resource custody, exact schemas and project tool admission remain separate checks.</figcaption>
+</figure>
+
+The implemented local service is administrator-only and requires explicit development flags, literal loopback addresses and different factory/provider hosts. The native browser qualification used IPv4 for forge and IPv6 for the owned stock pyfly service. GitHub, Figma, Sentry, Grafana and external Playwright OAuth retain their provider prerequisites. [Connected accounts](connected-accounts.md) explains the actual wizard, typed API and separate MCP admission steps.
+
+Source: [`oauth_provider_policies.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/oauth_provider_policies.py), [`connection_oauth.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/connection_oauth.py), [`oauth_resources.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/oauth_resources.py), [`mcp_registry.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/mcp_registry.py).
 
 ## PostgreSQL records and transaction boundaries
 
@@ -219,7 +248,7 @@ Pinned community skills are instruction adaptations with retained source, hash a
 | Official Codex / Claude Code | The official CLI's native tools and permission controls | A Python role tool list is advisory; it is not the CLI sandbox. |
 | Native browser QA | Fresh Docker context, declared local origin and bounded actions | Layout diagnostics and screenshots require actual visual/interaction review. |
 | Internet search | Explicit Brave or Tavily selection, retained credential revision and domain restrictions | Bounded cited results are untrusted references; no key goes to the model. |
-| Factory MCP | 96 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. |
+| Factory MCP | 108 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. |
 
 Flycanon retrieves `forge-<repository_id>` project context and shared framework references. Required retrieval failure prevents coding continuation. The retained citations/context digest support recovery. A ProductProject does not automatically create an aggregated memory workspace across its repositories.
 
@@ -231,6 +260,12 @@ Source: [`agent_roles.py`](https://github.com/fireflyframework/firefly-forge/blo
 
 The [learning architecture](learning.md) defines exact reuse eligibility, evidence-backed local procedure outcomes, observed failed checks and typed question/tool/review associations. Its diagrams separate PostgreSQL decision authority from flycanon retrieval and show where native fireflyframework-agentic workers provide proposals. The initial implementation adds scoped PostgreSQL records, native knowledge-first tools and explicit one-shot flycanon projection. Automatic retrieval from projected learning namespaces, classified negative repair controls and sharing between projects remain open; their contracts do not establish runtime acceptance.
 
+### Structured analytics boundary
+
+The optional [flyquery](https://github.com/fireflyframework/flyquery) architecture would query explicit, versioned project snapshots through an independently authorized service. It would never receive a direct connection to the factory ledger, retained private directory or flycanon database. Query results remain untrusted analytical evidence; factory records and cited canonical memory retain their existing authority.
+
+The [structured analytics design](structured-knowledge.md) records the assessed pipeline, known execution gaps, proposed native service boundaries and required authorization, snapshot and write-ahead checks. This release has no forge adapter or managed flyquery deployment.
+
 ## Runner ownership, collection and takeover
 
 <details class="forge-gallery" markdown="1">