From 8b85436f9cf211ec35f86c482db0ee232796b4be Mon Sep 17 00:00:00 2001 From: Mahdi Baghbani Date: Wed, 24 Jun 2026 12:46:07 +0000 Subject: [PATCH 1/3] add(deepwiki): add wiki page map Signed-off-by: Mahdi Baghbani --- .devin/wiki.json | 135 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 .devin/wiki.json diff --git a/.devin/wiki.json b/.devin/wiki.json new file mode 100644 index 0000000..577b911 --- /dev/null +++ b/.devin/wiki.json @@ -0,0 +1,135 @@ +{ + "repo_notes": [ + { + "author": "OCM maintainers", + "content": "This is a specification repository for Open Cloud Mesh. Normative sources are IETF-OCM.md for the main working-group draft, IETF-OCM-IP.md for the optional integration protocol companion draft, IETF-OCM-MLS.md for the optional MLS federated-groups companion draft, spec.yaml for the OpenAPI contract, and schemas/ocm-discovery.json for discovery validation. The generated IETF-*.xml files are build artifacts, not source of truth. The develop branch is in-progress; tagged releases and the changelog describe stable snapshots." + }, + { + "author": "OCM maintainers", + "content": "Preserve RFC 2119 requirement language exactly. Do not weaken or restate MUST, SHOULD, or MAY as softer guidance. Treat work/ and diagrams/ as non-normative supporting material. They may explain design intent, implementation research, or proposals, but they do not define protocol requirements. If older files mention IETF-RFC.md, treat that as legacy naming; the current core draft is IETF-OCM.md. Keep the main draft, companion drafts, and OpenAPI views clearly separated." + } + ], + "pages": [ + { + "title": "Open Cloud Mesh Specification Repository", + "purpose": "Provide a high-level map of the repository, including the main drafts, OpenAPI specification, JSON schema, diagrams, work-in-progress material, release history, and contribution workflow.", + "parent": null + }, + { + "title": "Main OCM Internet-Draft", + "purpose": "Document IETF-OCM.md as the primary Open Cloud Mesh working-group draft, including its scope, core roles, terminology, and overall structure.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "Treat this page as normative. Quote or closely track requirement language when summarizing behavior. Do not invent fields, endpoints, or implementation constraints that are not present in IETF-OCM.md." + } + ] + }, + { + "title": "OCM Flows and Discovery", + "purpose": "Cover the general flow, contact-establishment paths, and the discovery model from IETF-OCM.md, including /.well-known/ocm, capabilities, criteria, tokenEndPoint, and the receive-protocol advertisements.", + "parent": "Main OCM Internet-Draft" + }, + { + "title": "Shares, Notifications, and Resource Access", + "purpose": "Document share creation, notifications, and resource-access behavior from the main draft, with emphasis on protocol payloads, requirements, permissions, and receiver behavior.", + "parent": "Main OCM Internet-Draft" + }, + { + "title": "Code Flow and Security", + "purpose": "Explain the code-flow model, token exchange, HTTP message signatures, JWKS, MFA-related requirements, and the broader security model described in the main draft.", + "parent": "Main OCM Internet-Draft" + }, + { + "title": "Request for a Share", + "purpose": "Document the /request-share flow introduced in version 1.4.0, including the RequestShare payload, sender and receiver expectations, and how this feature differs from ordinary share creation.", + "parent": "Main OCM Internet-Draft" + }, + { + "title": "Share Lifecycle", + "purpose": "Document share deletion, share updating, and resharing behavior from the main draft, including lifecycle expectations beyond initial share creation.", + "parent": "Main OCM Internet-Draft" + }, + { + "title": "OpenAPI Specification", + "purpose": "Describe spec.yaml as the machine-readable API contract, including the documented endpoints, shared schemas, and how docs.html renders the specification through ReDoc.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "Use this page for wire-format structure and endpoint summaries, but defer behavioral semantics to the IETF drafts. The OpenAPI spec complements the draft; it does not replace the normative prose." + } + ] + }, + { + "title": "JSON Schemas", + "purpose": "Document schemas/ocm-discovery.json and explain how it relates to discovery behavior, OpenAPI structures, and the normative discovery section in the main draft.", + "parent": "OpenAPI Specification" + }, + { + "title": "OCM Integration Protocol", + "purpose": "Document IETF-OCM-IP.md as the companion draft for delegating protocol-specific work to external services such as WebDAV, SSH, or web application platforms.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "This is a companion draft, not the core OCM specification. Keep its requirements separate from the main draft unless the main draft explicitly depends on them." + } + ] + }, + { + "title": "OCM MLS Federated Groups", + "purpose": "Document IETF-OCM-MLS.md as the companion draft for federated groups based on Messaging Layer Security, including how it extends core OCM sharing concepts.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "This is an optional companion draft. Do not present MLS support as a baseline requirement for all OCM implementations." + } + ] + }, + { + "title": "Illustrative Diagrams", + "purpose": "Summarize the diagrams/ directory, including invitation flow, share-creation preflight, receiver discovery policy, resource access paths, and code-flow illustrations.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "These diagrams are explanatory and supplementary. They should help readers understand the protocol, but they must not be treated as additional normative requirements." + } + ] + }, + { + "title": "Working Material", + "purpose": "Describe the work/ directory as the staging area for proposals, research, and design notes that have not yet been formalized into the released specification.", + "parent": "Open Cloud Mesh Specification Repository", + "page_notes": [ + { + "author": "OCM maintainers", + "content": "Content under work/ is not normative. Present it as exploratory, provisional, or research-oriented material, even when it discusses realistic interop behavior." + } + ] + }, + { + "title": "Notifications Research", + "purpose": "Cover work/notifications/, including cross-stack notes, examples, discrepancies, and implementation research related to the notifications surface.", + "parent": "Working Material" + }, + { + "title": "Webapp Sharing Proposal", + "purpose": "Cover work/webapps/webapp-sharing.md as proposal material that informs the webapp sharing model and its relationship to the released specification.", + "parent": "Working Material" + }, + { + "title": "CI, IETF Submission, and Releases", + "purpose": "Document the GitHub workflows for OpenAPI validation, line-length checks, draft-to-XML generation, and GitHub Pages publishing, including the rule that contributors edit markdown sources rather than generated XML.", + "parent": "Open Cloud Mesh Specification Repository" + }, + { + "title": "Version History and Changelog", + "purpose": "Document the project history, release evolution, and notable protocol changes described in HISTORY.md and CHANGELOG.md, with emphasis on release milestones such as version 1.4.0.", + "parent": "Open Cloud Mesh Specification Repository" + } + ] +} From 3abb666025d8b1f59eb1154ce664c85a42fadf7a Mon Sep 17 00:00:00 2001 From: Mahdi Baghbani Date: Wed, 24 Jun 2026 12:47:22 +0000 Subject: [PATCH 2/3] docs: add deepwiki readme links Signed-off-by: Mahdi Baghbani --- .devin/wiki.json | 127 ++--------------------------------------------- README.md | 7 +++ 2 files changed, 11 insertions(+), 123 deletions(-) diff --git a/.devin/wiki.json b/.devin/wiki.json index 577b911..e6911cd 100644 --- a/.devin/wiki.json +++ b/.devin/wiki.json @@ -2,134 +2,15 @@ "repo_notes": [ { "author": "OCM maintainers", - "content": "This is a specification repository for Open Cloud Mesh. Normative sources are IETF-OCM.md for the main working-group draft, IETF-OCM-IP.md for the optional integration protocol companion draft, IETF-OCM-MLS.md for the optional MLS federated-groups companion draft, spec.yaml for the OpenAPI contract, and schemas/ocm-discovery.json for discovery validation. The generated IETF-*.xml files are build artifacts, not source of truth. The develop branch is in-progress; tagged releases and the changelog describe stable snapshots." + "content": "This is a specification repository for Open Cloud Mesh, not an implementation. Treat these as the normative sources, in priority order: IETF-OCM.md (the main IETF working-group draft), then spec.yaml (the OpenAPI contract) and schemas/ocm-discovery.json (discovery validation). IETF-OCM-IP.md and IETF-OCM-MLS.md are optional companion drafts. The IETF-*.xml files are generated build artifacts, not source of truth; contributors edit the markdown sources only. The develop branch is work in progress, while git tags and CHANGELOG.md describe stable released versions." }, { "author": "OCM maintainers", - "content": "Preserve RFC 2119 requirement language exactly. Do not weaken or restate MUST, SHOULD, or MAY as softer guidance. Treat work/ and diagrams/ as non-normative supporting material. They may explain design intent, implementation research, or proposals, but they do not define protocol requirements. If older files mention IETF-RFC.md, treat that as legacy naming; the current core draft is IETF-OCM.md. Keep the main draft, companion drafts, and OpenAPI views clearly separated." - } - ], - "pages": [ - { - "title": "Open Cloud Mesh Specification Repository", - "purpose": "Provide a high-level map of the repository, including the main drafts, OpenAPI specification, JSON schema, diagrams, work-in-progress material, release history, and contribution workflow.", - "parent": null + "content": "When documenting protocol behavior, preserve RFC 2119 keywords (MUST, SHOULD, MAY) exactly and do not restate them as softer guidance. Keep the main draft, the OCM-IP and OCM-MLS companion drafts, and the OpenAPI views clearly separated, and do not present companion-draft or webapp-integration features as baseline requirements for every implementation. The OpenAPI spec and its ReDoc rendering describe API shape; defer to IETF-OCM.md for semantics. Material under work/ and diagrams/ is non-normative: it explains design intent, research, and proposals and must not be treated as protocol requirements. If older files mention IETF-RFC.md, that is legacy naming for the current IETF-OCM.md." }, { - "title": "Main OCM Internet-Draft", - "purpose": "Document IETF-OCM.md as the primary Open Cloud Mesh working-group draft, including its scope, core roles, terminology, and overall structure.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "Treat this page as normative. Quote or closely track requirement language when summarizing behavior. Do not invent fields, endpoints, or implementation constraints that are not present in IETF-OCM.md." - } - ] - }, - { - "title": "OCM Flows and Discovery", - "purpose": "Cover the general flow, contact-establishment paths, and the discovery model from IETF-OCM.md, including /.well-known/ocm, capabilities, criteria, tokenEndPoint, and the receive-protocol advertisements.", - "parent": "Main OCM Internet-Draft" - }, - { - "title": "Shares, Notifications, and Resource Access", - "purpose": "Document share creation, notifications, and resource-access behavior from the main draft, with emphasis on protocol payloads, requirements, permissions, and receiver behavior.", - "parent": "Main OCM Internet-Draft" - }, - { - "title": "Code Flow and Security", - "purpose": "Explain the code-flow model, token exchange, HTTP message signatures, JWKS, MFA-related requirements, and the broader security model described in the main draft.", - "parent": "Main OCM Internet-Draft" - }, - { - "title": "Request for a Share", - "purpose": "Document the /request-share flow introduced in version 1.4.0, including the RequestShare payload, sender and receiver expectations, and how this feature differs from ordinary share creation.", - "parent": "Main OCM Internet-Draft" - }, - { - "title": "Share Lifecycle", - "purpose": "Document share deletion, share updating, and resharing behavior from the main draft, including lifecycle expectations beyond initial share creation.", - "parent": "Main OCM Internet-Draft" - }, - { - "title": "OpenAPI Specification", - "purpose": "Describe spec.yaml as the machine-readable API contract, including the documented endpoints, shared schemas, and how docs.html renders the specification through ReDoc.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "Use this page for wire-format structure and endpoint summaries, but defer behavioral semantics to the IETF drafts. The OpenAPI spec complements the draft; it does not replace the normative prose." - } - ] - }, - { - "title": "JSON Schemas", - "purpose": "Document schemas/ocm-discovery.json and explain how it relates to discovery behavior, OpenAPI structures, and the normative discovery section in the main draft.", - "parent": "OpenAPI Specification" - }, - { - "title": "OCM Integration Protocol", - "purpose": "Document IETF-OCM-IP.md as the companion draft for delegating protocol-specific work to external services such as WebDAV, SSH, or web application platforms.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "This is a companion draft, not the core OCM specification. Keep its requirements separate from the main draft unless the main draft explicitly depends on them." - } - ] - }, - { - "title": "OCM MLS Federated Groups", - "purpose": "Document IETF-OCM-MLS.md as the companion draft for federated groups based on Messaging Layer Security, including how it extends core OCM sharing concepts.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "This is an optional companion draft. Do not present MLS support as a baseline requirement for all OCM implementations." - } - ] - }, - { - "title": "Illustrative Diagrams", - "purpose": "Summarize the diagrams/ directory, including invitation flow, share-creation preflight, receiver discovery policy, resource access paths, and code-flow illustrations.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "These diagrams are explanatory and supplementary. They should help readers understand the protocol, but they must not be treated as additional normative requirements." - } - ] - }, - { - "title": "Working Material", - "purpose": "Describe the work/ directory as the staging area for proposals, research, and design notes that have not yet been formalized into the released specification.", - "parent": "Open Cloud Mesh Specification Repository", - "page_notes": [ - { - "author": "OCM maintainers", - "content": "Content under work/ is not normative. Present it as exploratory, provisional, or research-oriented material, even when it discusses realistic interop behavior." - } - ] - }, - { - "title": "Notifications Research", - "purpose": "Cover work/notifications/, including cross-stack notes, examples, discrepancies, and implementation research related to the notifications surface.", - "parent": "Working Material" - }, - { - "title": "Webapp Sharing Proposal", - "purpose": "Cover work/webapps/webapp-sharing.md as proposal material that informs the webapp sharing model and its relationship to the released specification.", - "parent": "Working Material" - }, - { - "title": "CI, IETF Submission, and Releases", - "purpose": "Document the GitHub workflows for OpenAPI validation, line-length checks, draft-to-XML generation, and GitHub Pages publishing, including the rule that contributors edit markdown sources rather than generated XML.", - "parent": "Open Cloud Mesh Specification Repository" - }, - { - "title": "Version History and Changelog", - "purpose": "Document the project history, release evolution, and notable protocol changes described in HISTORY.md and CHANGELOG.md, with emphasis on release milestones such as version 1.4.0.", - "parent": "Open Cloud Mesh Specification Repository" + "author": "OCM maintainers", + "content": "Give focused coverage to: the discovery endpoint /.well-known/ocm including capabilities, criteria, tokenEndPoint, and the protocol receive advertisements such as webdav-receive, webapp-receive, and ssh-receive; establishing contact and the invite flow; share creation, share acceptance notifications, and resource access; the Code Flow, token exchange, HTTP message signatures, JWKS, and multi-factor authentication; the /request-share flow added in version 1.4.0; the webapp protocol refactor to POST requests and the Code Flow added in 1.4.0; share deletion, updating, and resharing; the Directory Service in Appendix C; and the object models in Appendix D. Note that the legacy /ocm-provider discovery endpoint was removed in 1.4.0 in favor of /.well-known/ocm. For the notifications surface, the work/notifications research and the work/webapps/webapp-sharing.md proposal are background research, not the released specification." } ] } diff --git a/README.md b/README.md index ba977b5..9e4f329 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,8 @@ # Open Cloud Mesh Protocol Specification +[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/cs3org/OCM-API) + This repository contains the text of the [Open Cloud Mesh IETF Drafts](https://datatracker.ietf.org/doc/draft-ietf-ocm-open-cloud-mesh/), as well as the equivalent [OpenAPI](https://github.com/OAI/OpenAPI-Specification) (fka Swagger) specification for its API rendered as HTML (by [ReDoc](https://github.com/Redocly/redoc)). The documents are available as follows: @@ -12,6 +14,11 @@ The documents are available as follows: * **Latest official version, 1.4.0**: [Main RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM.md) | [Integration Protocol RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM-IP.md) | [MLS RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM-MLS.md) | [API spec](https://cs3org.github.io/OCM-API/docs.html?branch=v1.4.0&repo=OCM-API&user=cs3org) * Development branch: [Main RFC Draft](IETF-OCM.md) | [Integration Protocol RFC Draft](IETF-OCM-IP.md) | [MLS RFC Draft](IETF-OCM-MLS.md) | [API spec](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org) +For a navigable overview of this repository, see +[DeepWiki](https://deepwiki.com/cs3org/OCM-API). Normative protocol text +and the OpenAPI reference are the IETF drafts and ReDoc site linked +above. + [SemVer](https://semver.org) versioning applies to OCM, and backwards compatibility is supported unless stated otherwise by an implementation. ## Testing From ffe007e41fe9e649da5f2d1a8a2eb7974f958c54 Mon Sep 17 00:00:00 2001 From: Giuseppe Lo Presti Date: Thu, 25 Jun 2026 07:48:25 +0200 Subject: [PATCH 3/3] Update README.md --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9e4f329..7cd502b 100644 --- a/README.md +++ b/README.md @@ -14,10 +14,8 @@ The documents are available as follows: * **Latest official version, 1.4.0**: [Main RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM.md) | [Integration Protocol RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM-IP.md) | [MLS RFC Draft](https://github.com/cs3org/OCM-API/blob/v1.4.0/IETF-OCM-MLS.md) | [API spec](https://cs3org.github.io/OCM-API/docs.html?branch=v1.4.0&repo=OCM-API&user=cs3org) * Development branch: [Main RFC Draft](IETF-OCM.md) | [Integration Protocol RFC Draft](IETF-OCM-IP.md) | [MLS RFC Draft](IETF-OCM-MLS.md) | [API spec](https://cs3org.github.io/OCM-API/docs.html?branch=develop&repo=OCM-API&user=cs3org) -For a navigable overview of this repository, see -[DeepWiki](https://deepwiki.com/cs3org/OCM-API). Normative protocol text -and the OpenAPI reference are the IETF drafts and ReDoc site linked -above. +For a navigable, AI-generated overview of this repository, see +[DeepWiki](https://deepwiki.com/cs3org/OCM-API). [SemVer](https://semver.org) versioning applies to OCM, and backwards compatibility is supported unless stated otherwise by an implementation.