Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,22 @@ All notable changes to this project will be documented in this file. The format

## [Unreleased]

## [1.0.0] - 2026-08-11

### Changed

- [#39](https://github.com/mohanagy/miftah/issues/39) Established the stable Semantic Versioning contract for documented configuration formats, CLI and MCP names, audit records, package exports, and the plugin API. The v1 candidate preserves the tested 0.5.8 runtime surface while promoting the compatibility, migration, documentation, security, and cross-platform gates accumulated across the pre-1.0 line.
- [#36](https://github.com/mohanagy/miftah/issues/36) Added a repeatable, research-only evaluation of MCP tool-description quarantine: exact descriptor drift is detected with canonical hashes, while a deliberately small heuristic corpus records both false positives and missed malicious descriptions. The published recommendation defers runtime quarantine until representative design-partner evidence shows acceptable value, approval churn, and recovery behavior; this prototype is not a production security control and does not claim protection after credentials reach an operator-approved upstream.

### Security

- [#373](https://github.com/mohanagy/miftah/issues/373) Updated the exact transitive security resolutions to `fast-uri` 3.1.5, `ip-address` 10.3.1, `hono` 4.12.34, `brace-expansion` 5.0.9, and `nanoid` 3.3.17 after newly disclosed host-confusion, SSRF/trust-classification, ReDoS, and denial-of-service advisories. Package contracts reject stale nested copies, and both production-only and full npm audits report zero known vulnerabilities without changing Miftah's runtime API.

### Validation

- The maintainer reported **5/5 completed external workflows**, **3 returning participants**, **3 unaided evaluators**, and a completed security report, then authorized closure of the related v1 issues. This release record preserves that as maintainer attestation: the participant records and completed report were not independently inspected during release preparation, and no additional provider, reviewer, severity, or remediation facts are inferred here.
- Publication remains protected: the finalized candidate is promoted from `development` to the exact current `main` commit, released as `v1.0.0`, and published only through protected OIDC publication with registry provenance, fresh-install, and signature verification recorded on #39.

## [0.5.8] - 2026-08-09

### Fixed
Expand Down Expand Up @@ -216,4 +228,4 @@ All notable changes to this project will be documented in this file. The format

## Release policy

Miftah is experimental and pre-1.0, so incompatible changes may occur between minor versions and must be called out here. For each release, maintainers move **Unreleased** entries into a dated version section, update `package.json` and `package-lock.json` together using npm tooling, and publish a GitHub release tagged `v<package-version>`. The release workflow publishes only after the tag, ancestry, tests, build, CLI smoke test, and package contents are verified.
Miftah 1.x follows Semantic Versioning for the public compatibility surfaces documented in the library, CLI, configuration, audit, MCP-management, and plugin references. Compatible fixes use patch releases, additive compatible features use minor releases, and incompatible public changes require a new major release with an explicit **Unreleased** entry and migration guidance. For each release, maintainers move **Unreleased** entries into a dated version section, update `package.json` and `package-lock.json` together using npm tooling, and publish a GitHub release tagged `v<package-version>`. The release workflow publishes only after the tag, ancestry, tests, build, CLI smoke test, and package contents are verified.
6 changes: 3 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ Claude, Cursor, or VS Code

Miftah itself has no cloud service or telemetry. It adds local profile selection, credential references, policy, approvals, redaction, diagnostics, and optional audit metadata around an upstream; it does not replace that upstream or widen what the upstream supports.

> **Status:** Miftah is experimental and pre-1.0. Interfaces and security behavior may change between minor versions. External multi-account and returning-user validation in [#25](https://github.com/mohanagy/miftah/issues/25) and [#88](https://github.com/mohanagy/miftah/issues/88) remains open.
> **Status:** Miftah 1.0 is the stable v1 release line. Documented public compatibility surfaces follow Semantic Versioning. The external workflow and security-review gates were closed by maintainer attestation in [#39](https://github.com/mohanagy/miftah/issues/39); the source participant records and completed security report are not published in this repository.

Already using Miftah? See [What is in 0.5 and how to use it](docs/whats-new-in-0.5.md) for the release's guided setup, profile-management, Console, OAuth, and upgrade paths.
Upgrading from Miftah 0.5? See [What is in 0.5 and how to use it](docs/whats-new-in-0.5.md) for the guided setup, profile-management, Console, OAuth, and upgrade paths introduced before the stable line.

## Is Miftah for you?

Expand Down Expand Up @@ -53,7 +53,7 @@ Install Miftah, then choose the terminal wizard or the browser Console. Both use
### 1. Install the current release

```bash
npm install -g @lubab/miftah@0.5.8
npm install -g @lubab/miftah@1.0.0
miftah version
```

Expand Down
2 changes: 1 addition & 1 deletion docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Usage: miftah [command] [options]

The root command list includes `serve`, `dashboard`, `console`, `validate`, `doctor`, `schema`, `setup`, `init`, `migrate-config`, `profile list|set-default|set-description|rename|remove|test`, `connection add|list|status|test`, `auth connect|reauth|disconnect`, `list-tools`, `test-profile`, `logs`, `audit-export`, `audit-verify`, and `version`. With no command, Miftah runs `serve`.

Documented command names, options, JSON success forms, and exit categories are compatibility contracts. An incompatible CLI removal, rename, required-option change, or semantic output change requires the pre-1.0 deprecation/removal process in the [public compatibility policy](library-api.md#compatibility-policy).
Documented command names, options, JSON success forms, and exit categories are compatibility contracts. An incompatible CLI removal, rename, required-option change, or semantic output change requires a new major release and the deprecation/removal process in the [public compatibility policy](library-api.md#compatibility-policy).

`--help` and `-h` print help and exit successfully. They can appear before or after a command. Help never reads configuration, resolves secrets, or starts an upstream.

Expand Down
2 changes: 1 addition & 1 deletion docs/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ Version `"2"` is the prior canonical non-OAuth format. Version `"3"` keeps its e

For version 1, the migrator changes only aliases with proven equivalent behavior: `"http"` becomes `"streamable-http"`, the plaintext opt-in moves to `secrets.allowPlaintextSecrets`, and redundant force-on redaction declarations are removed. It fails closed for conflicting plaintext options or unrelated unsupported fields rather than discarding them. A version-2 input preserves the existing configuration while changing only the format version; it never infers native OAuth from a static `Authorization` header. A version-3 input is validated and reported as unchanged; `--write` then creates no backup and performs no write.

Versions 1 and 2 will remain accepted through at least the first published pre-1.0 minor release after version 3 ships. Removing either version requires a later minor release, an **Unreleased** changelog entry, and a documented explicit migration path. Keep a byte-for-byte historical fixture for every supported released format in release CI.
Versions 1, 2, and 3 remain accepted throughout the Miftah 1.x release line. Removing version 1 or 2 requires a new major release, an **Unreleased** changelog entry, and a documented explicit migration path. Keep a byte-for-byte historical fixture for every supported released format in release CI.

For strict starter configurations, use the versioned `init` catalog rather than treating generic command examples as trusted upstream recommendations. The [preset and client compatibility matrix](presets-and-clients.md) records exact pins, required inputs, upstream provenance, and the validation boundary for every catalog entry.

Expand Down
8 changes: 6 additions & 2 deletions docs/independent-security-review.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# Independent security review brief

This brief defines the external review required by issues #37 and #39. It turns the public [threat model](threat-model.md) into a reviewable engagement without claiming that a review has happened.
This brief defines the external review required by issues #37 and #39 and records the evidence boundary for the maintainer's completion attestation. It turns the public [threat model](threat-model.md) into a reviewable engagement without inventing report details that were not supplied to the repository.

## Target and independence

The engagement baseline is the current published release, `@lubab/miftah@0.5.8`. Before work starts, the maintainer and reviewer must record the exact commit and package version under review, the upstream dependencies or fixtures used, the operating systems exercised, and the review dates. The eventual v1 release candidate must receive either a final review at its exact commit or a reviewer-accepted delta review from the recorded baseline.
The engagement baseline is the published `@lubab/miftah@0.5.8`; the stable release candidate is `@lubab/miftah@1.0.0`. The maintainer and reviewer must record the exact commit and package version under review, the upstream dependencies or fixtures used, the operating systems exercised, and the review dates. The v1 release candidate must receive either a final review at its exact commit or a reviewer-accepted delta review from the recorded baseline.

The reviewer supplies an independence declaration covering employment, contribution, financial, and other material relationships with Miftah and its maintainers. A maintainer self-review, automated scanner, dependency report, or AI-only review is useful input but does not satisfy this independent gate.

## Recorded review status

On 2026-08-11, the maintainer reported that the security report was completed and explicitly authorized closure of #37. That statement is recorded as maintainer attestation. The completed report, reviewer attribution and independence declaration, target commit, severity counts, remediation or retest record, public completion summary, and v1 candidate delta acceptance were not supplied for this release-preparation session and therefore were not independently inspected. Maintainer attestation or deidentified records alone do not close the independent-review criterion in #39. This status does not create or infer the missing facts; #39 must retain the exact protected-release evidence and any reviewer-approved final-candidate reconciliation used for publication.

## Review scope

Review the security claims and boundaries in [`threat-model.md`](threat-model.md), [`security.md`](security.md), and the OAuth and Console threat model. At minimum, cover:
Expand Down
6 changes: 3 additions & 3 deletions docs/library-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The configuration contract exposes `ActiveProfileStateScope`, `AuditConfig`, `Au

`MiftahConfigVersion` is the union of format versions accepted by this installed release. `CURRENT_CONFIG_VERSION` is the version generated by presets; it does not cause `loadConfig` to rewrite a legacy file. Use the explicit [configuration migration command](cli.md#migrate-config) when an on-disk upgrade is intended.

`MiftahConfig` is a version-discriminated union. A `version: "1"` value retains the documented compatibility aliases; `version: "2"` accepts the canonical static-credential surface; and `version: "3"` adds opaque `OAuthConfig` bindings. Version 3 contains no token, refresh-token, client-secret, or callback fields; an exact OAuth binding enables the internal standards-compatible remote Streamable HTTP authorization runtime. This intentional pre-1.0 type-surface change means application-side composition must use an intersection such as `type AppConfig = MiftahConfig & { readonly appMetadata: AppMetadata }`, rather than `interface AppConfig extends MiftahConfig`; strip application-only metadata before strict Miftah config validation.
`MiftahConfig` is a version-discriminated union. A `version: "1"` value retains the documented compatibility aliases; `version: "2"` accepts the canonical static-credential surface; and `version: "3"` adds opaque `OAuthConfig` bindings. Version 3 contains no token, refresh-token, client-secret, or callback fields; an exact OAuth binding enables the internal standards-compatible remote Streamable HTTP authorization runtime. The pre-1.0 version-3 type-surface change means application-side composition must use an intersection such as `type AppConfig = MiftahConfig & { readonly appMetadata: AppMetadata }`, rather than `interface AppConfig extends MiftahConfig`; strip application-only metadata before strict Miftah config validation.

`AuditRotationConfig` requires `retainFiles` (maximum `2000`) plus at least one positive trigger (`maxBytes` or `maxAgeMs`). `AuditIntegrityConfig` currently exposes the explicit local `"sha256-chain"` option only. Both configure the runtime journal; journal writers, readers, and CLI export/verification implementations remain internal.

Expand All @@ -55,13 +55,13 @@ Programmatic diagnostics expose `ConfigDiagnostic`, `MiftahErrorCode`, and `Mift

## Compatibility policy

Miftah is pre-1.0. The following are public compatibility surfaces. Additive behavior may ship in a patch release when it preserves existing callers; a removal, rename, semantic reinterpretation, or incompatible output change requires a minor release and an explicit **Unreleased** changelog entry.
Starting with Miftah 1.0, these public surfaces follow Semantic Versioning. Compatible fixes may ship in a patch release, and additive compatible behavior may ship in a minor release. A removal, rename, semantic reinterpretation, or incompatible output change requires a new major release, an explicit **Unreleased** changelog entry, and migration guidance. A security correction may remove unsafe behavior without preserving an exploitable contract, but its impact and safe replacement must be documented.

| Surface | Contract |
| --- | --- |
| Configuration formats | `MiftahConfigVersion` and `CURRENT_CONFIG_VERSION` describe the installed release. Supported historical formats remain loadable for their documented window; upgrades are explicit through `miftah migrate-config`, never an implicit load-time rewrite. |
| CLI | Documented command names, flags, JSON success shapes, and exit categories are public. A deprecated form remains available through the announced window and gets an actionable replacement. |
| MCP management namespace | `miftah_*` management tool names and multi-upstream `<upstream>__<tool>`, resource, and prompt namespaces are public client-facing identifiers. Renaming or changing their routing meaning follows the minor-release/remediation rule. |
| MCP management namespace | `miftah_*` management tool names and multi-upstream `<upstream>__<tool>`, resource, and prompt namespaces are public client-facing identifiers. Renaming or changing their routing meaning follows the major-release/remediation rule. |
| Audit JSONL | Persisted records carry an immutable schema version. Existing schema versions remain readable for their announced window; incompatible record changes need a documented reader/export migration path. |
| Package root | The documented runtime and type exports on this page are public; internal deep imports are not. |
| Plugin subpath | `@lubab/miftah/plugin-api` is an ABI-versioned authoring surface. A new incompatible ABI uses a new `apiVersion`; it does not silently reinterpret an existing one. |
Expand Down
14 changes: 7 additions & 7 deletions docs/oauth-console-validation.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# OAuth and Console validation

This page records what Miftah's release gate proves for native remote OAuth and the optional local Console, what it deliberately does not prove, and which external evidence is still missing. It is an evidence record, not a claim that every OAuth provider is supported.
This page records what Miftah's release gate proves for native remote OAuth and the optional local Console, what it deliberately does not prove, and how maintainer-attested external evidence is recorded. It is an evidence record, not a claim that every OAuth provider is supported.

## Automated compatibility gate

Expand Down Expand Up @@ -37,15 +37,15 @@ For provider-adapter-backed or upstream-owned OAuth, follow the provider's own r

## Release status and limitations

OAuth and Console are being validated for a pre-v1 feature release. Passing this automated gate is required release evidence, but it is not v1.0 readiness and does not close the demand or external-validation gates by itself. The current support classes and manual fallbacks remain defined in the [OAuth support matrix](oauth-support.md#support-matrix).
OAuth and Console are included in the `@lubab/miftah@1.0.0` release candidate. They become part of the stable v1 release only after exact-main protected publication and registry verification. The automated gate remains required evidence, but it does not prove live-provider behavior, external adoption, or account intent by itself. The current support classes and manual fallbacks remain defined in the [OAuth support matrix](oauth-support.md#support-matrix).

## External design-partner evidence

Snapshot date: 2026-08-11. Evaluator target: `@lubab/miftah@0.5.8`.
Snapshot date: 2026-08-11. Evaluator baseline: `@lubab/miftah@0.5.8`. Stable release candidate: `@lubab/miftah@1.0.0`.

- Interested external users: 5
- Recorded completed external workflows: 0
- Recorded returning external users: 0
- Recorded unaided README evaluators: 0
- Recorded completed external workflows: 5
- Recorded returning external users: 3
- Recorded unaided README evaluators: 3

The external design-partner gate remains open. Use the [v1 external evaluation](v1-evaluation.md) protocol to define a completed real workflow, a later-session return, unaided participation, version pinning, and the deidentified public record. Never record credentials, OAuth codes, tokens, provider payloads, or personal account identifiers.
These counts are a maintainer attestation recorded on [#39](https://github.com/mohanagy/miftah/issues/39), not independently inspected participant evidence. The private participant records and public deidentified row-level rollup were not supplied during release preparation, so this page does not infer provider coverage, dates, clients, operating systems, or participant-specific outcomes beyond the three counters above. The [v1 external evaluation](v1-evaluation.md) protocol remains the definition of a completed real workflow, later-session return, unaided participation, version pinning, and safe deidentified record. Never record credentials, OAuth codes, tokens, provider payloads, or personal account identifiers.
Loading
Loading