diff --git a/contracts/command-catalog.json b/contracts/command-catalog.json index ca1388d..f44e01d 100644 --- a/contracts/command-catalog.json +++ b/contracts/command-catalog.json @@ -11855,12 +11855,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.upload", "cli": "museoncli html-documents +upload", @@ -11872,7 +11872,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides.", + "summary": "Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11882,12 +11882,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.list", "cli": "museoncli html-documents +list", @@ -11899,7 +11899,7 @@ "risk_level": "read", "shortcut": "+list", "stability": "stable", - "summary": "List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides.", + "summary": "List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": false, "transport": "agent_cli_api" }, @@ -11909,12 +11909,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.share", "cli": "museoncli html-documents +share", @@ -11926,7 +11926,7 @@ "risk_level": "write", "shortcut": "+share", "stability": "stable", - "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides.", + "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11936,12 +11936,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.unshare", "cli": "museoncli html-documents +unshare", @@ -11953,7 +11953,7 @@ "risk_level": "write", "shortcut": "+unshare", "stability": "stable", - "summary": "Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides.", + "summary": "Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11963,12 +11963,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.folder-create", "cli": "museoncli html-documents folder +create", @@ -11980,7 +11980,7 @@ "risk_level": "write", "shortcut": "+create", "stability": "stable", - "summary": "Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides.", + "summary": "Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -11990,12 +11990,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.install-defaults", "cli": "museoncli html-documents +install-defaults", @@ -12007,7 +12007,7 @@ "risk_level": "write", "shortcut": "+install-defaults", "stability": "stable", - "summary": "Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides.", + "summary": "Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" } @@ -64521,12 +64521,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.folder-create", "cli": "museoncli html-documents folder +create", @@ -64615,7 +64615,7 @@ "risk_level": "write", "shortcut": "+create", "stability": "stable", - "summary": "Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides.", + "summary": "Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -64625,12 +64625,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.install-defaults", "cli": "museoncli html-documents +install-defaults", @@ -64711,7 +64711,7 @@ "risk_level": "write", "shortcut": "+install-defaults", "stability": "stable", - "summary": "Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides.", + "summary": "Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -64721,12 +64721,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.list", "cli": "museoncli html-documents +list", @@ -64815,7 +64815,7 @@ "risk_level": "read", "shortcut": "+list", "stability": "stable", - "summary": "List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides.", + "summary": "List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": false, "transport": "agent_cli_api" }, @@ -64825,12 +64825,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.share", "cli": "museoncli html-documents +share", @@ -64935,7 +64935,7 @@ "risk_level": "write", "shortcut": "+share", "stability": "stable", - "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides.", + "summary": "Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -64945,12 +64945,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.unshare", "cli": "museoncli html-documents +unshare", @@ -65038,7 +65038,7 @@ "risk_level": "write", "shortcut": "+unshare", "stability": "stable", - "summary": "Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides.", + "summary": "Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, @@ -65048,12 +65048,12 @@ "enforcement": "museon_server", "organization_bound": true, "required_roles": [ - "organization_member" + "staff" ], "required_scopes": [ "agent_cli.access" ], - "resource_policy": "server_evaluated_organization_and_resource_access" + "resource_policy": "staff_with_organization_asset_access" }, "capability_key": "html-documents.upload", "cli": "museoncli html-documents +upload", @@ -65177,7 +65177,7 @@ "risk_level": "write", "shortcut": "+upload", "stability": "stable", - "summary": "Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides.", + "summary": "Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides.", "supports_dry_run": true, "transport": "agent_cli_api" }, diff --git a/contracts/task-index.yaml b/contracts/task-index.yaml index 4be993b..20cb4e7 100644 --- a/contracts/task-index.yaml +++ b/contracts/task-index.yaml @@ -872,7 +872,7 @@ chapters: title: Upload and share HTML pages with customers when: ["html document", "html library", "upload html", "html folder", "share html", "HTML 文档", "文档库", "客户分享", "网页分享"] steps: - - html-documents.list: "folder is omitted, root, or a folder id; q searches titles." + - html-documents.list: "Museon staff only, plus asset read; the server decides. folder is omitted, root, or a folder id; q searches titles." - html-documents.folder-create: "One level only. The body is the name. No idempotency key: after an unknown outcome, list first." - html-documents.upload: "Public by default: give the customer share_url. --share-slug chooses a custom link name; --private keeps the document internal, even when a name is reserved. A second upload creates a second document; after an unknown result, list before retrying." - html-documents.share: "Enable sharing for an existing document. Omit link options to keep the custom name, --share-slug to rename, or --random-link to clear it. Old names stay reserved to this document." diff --git a/docs/agent-discoverability.md b/docs/agent-discoverability.md index 71ebad8..d7633e0 100644 --- a/docs/agent-discoverability.md +++ b/docs/agent-discoverability.md @@ -608,12 +608,12 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. | command | risk | dry-run | confirm | execution | summary | |---|---|---|---|---|---| -| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. | -| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides. | -| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides. | -| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides. | -| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. | -| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides. | +| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | @@ -633,7 +633,9 @@ after changing specs; `tests/test_docs_sync.py` fails CI on drift. - Requests act in the organization chosen with `museoncli org select` (`X-Organization-Id`); pass `--organization-id ` on a domain command to address another organization for one call. Catalog entries mark this with `organization_bound` - and roles `organization_member` / `organization_admin_or_staff`. Since 1.0 no command + and roles `organization_member` / `organization_admin_or_staff`. `html-documents` + stays organization-bound and also requires `staff` + (`staff_with_organization_asset_access`); the server enforces both. Since 1.0 no command takes a workspace; only `agentic-campaign` and `hireaicreator` keep their 0.25 `--workspace-id` and `workspace_bound` mirror until they move to organizations. - Envelopes carry an `organization` key (`{id, name}` or `null`) and no `workspace` key diff --git a/docs/domain-command-framework.md b/docs/domain-command-framework.md index 3ce843c..a5834b5 100644 --- a/docs/domain-command-framework.md +++ b/docs/domain-command-framework.md @@ -40,6 +40,9 @@ any more: organizations are the only unit of access. (`organization_member`, `organization_admin_or_staff`) and `resource_policy: server_evaluated_organization_and_resource_access`: the server evaluates organization role, Campaign scope and target-resource access on every request. + `html-documents` keeps `organization_bound` and adds `required_roles: staff` with + `resource_policy: staff_with_organization_asset_access` (staff, and still the + organization's asset permission). The CLI records that and does not enforce it. - 1.0 removed `museoncli workspace list|current|select`, every `--workspace-id` and every `workspace_id` input. `agentic-campaign` and `hireaicreator` are the exception and keep their 0.25 behaviour until they move to organizations; all of it lives in @@ -642,12 +645,12 @@ The tables below are generated — edit code, then run | command | risk | dry-run | confirm | execution | summary | |---|---|---|---|---|---| -| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. | -| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Anyone who can read the organization's assets can list; the server decides. | -| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Needs asset edit on the organization; the server decides. | -| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Needs asset edit on the organization; the server decides. | -| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Needs asset edit on the organization; the server decides. | -| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Needs asset edit on the organization; the server decides. | +| `html-documents +upload` | write | yes | — | direct | Upload one local HTML file with --title and return a Museon share_url that customers can open without signing in. Anyone with the link can view it; use --private to keep it inside the organization. --share-slug chooses a custom link name (or reserves it for a private upload). The stored filename is --filename, or the file's basename when it is one *.html or *.htm name with no '..' or slash; otherwise the server names it from the title. Titles may repeat, so a second upload is a second document: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +list` | read | — | — | direct | List this organization's HTML documents and its one-level folders. --q searches titles. --folder is omitted (every document), root (no folder), or a folder id. Museon staff only, and needs asset read on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +share` | write | yes | — | direct | Enable customer sharing for one existing HTML document. Anyone with the returned share_url can view it without signing in. Omit link options to keep its current custom name; use --share-slug to set or rename it, or --random-link to clear the custom name. Old custom names stop resolving after a rename and stay reserved to this document. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +unshare` | write | yes | — | direct | Stop customer sharing for one HTML document. Its current link stops working for new visits; already downloaded copies cannot be recalled. The document stays in the organization library. Sharing again restores its custom name when one is reserved, or creates a new random link. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents folder +create` | write | yes | — | direct | Create one folder in this organization's HTML document library. Folders do not nest, and the request sends the name only. No idempotency key: after an unknown outcome, +list before retrying. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | +| `html-documents +install-defaults` | write | yes | — | direct | Copy the three built-in HTML guides into this organization. Running it again does not add duplicates. Museon staff only, and needs asset edit on the organization. A staff API key does not gain staff support outside its organization role, and stays inside the organization it was issued in. The server decides. | diff --git a/docs/guide.md b/docs/guide.md index e598b14..75f39e1 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -800,7 +800,7 @@ See: `organizations` `museoncli guide html-documents` · when: html document; html library; upload html; html folder; share html; HTML 文档; 文档库; 客户分享; 网页分享 -1. `museoncli html-documents +list` (read): folder is omitted, root, or a folder id; q searches titles. +1. `museoncli html-documents +list` (read): Museon staff only, plus asset read; the server decides. folder is omitted, root, or a folder id; q searches titles. 2. `museoncli html-documents folder +create --name ` (write): One level only. The body is the name. No idempotency key: after an unknown outcome, list first. 3. `museoncli html-documents +upload --file --title ` (write): Public by default: give the customer share_url. --share-slug chooses a custom link name; --private keeps the document internal, even when a name is reserved. A second upload creates a second document; after an unknown result, list before retrying. 4. `museoncli html-documents +share --id <html-documents-id>` (write): Enable sharing for an existing document. Omit link options to keep the custom name, --share-slug to rename, or --random-link to clear it. Old names stay reserved to this document. diff --git a/museoncli/domains/html_documents.py b/museoncli/domains/html_documents.py index 225dc3d..f39c0d8 100644 --- a/museoncli/domains/html_documents.py +++ b/museoncli/domains/html_documents.py @@ -2,7 +2,10 @@ Documents and one-level folders belong to the organization in the path. The CLI sends that organization as ``X-Organization-Id`` and never a workspace or a -``parent_id``. Reads need asset read and writes need asset edit; the server decides. +``parent_id``. Private management is Museon staff plus the organization's asset +permission (read to list, edit to write). That is catalog metadata only: the CLI +does not enforce it, and the server decides. A customer share link is anonymous +and is not one of these commands. """ from __future__ import annotations @@ -33,7 +36,16 @@ _MAX_FILENAME = 180 _FOLDER = "72defd40-39ad-40d3-8105-8f23a9a016da" _DOCUMENT = "11111111-1111-4111-8111-111111111111" -_EDIT = " Needs asset edit on the organization; the server decides." +_STAFF_ROLES = ("staff",) +_STAFF_POLICY = "staff_with_organization_asset_access" +_STAFF_KEY = ( + "A staff API key does not gain staff support outside its organization role, and " + "stays inside the organization it was issued in. The server decides." +) +_EDIT = ( + " Museon staff only, and needs asset edit on the organization. " + _STAFF_KEY +) +_READ = "Museon staff only, and needs asset read on the organization. " + _STAFF_KEY _SHARE_SLUG = { "type": ["string", "null"], "minLength": 3, @@ -490,6 +502,8 @@ def specs() -> list[CommandSpec]: add_arguments=_add_upload_arguments, build_arguments=_build_upload_arguments, supports_dry_run=True, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), CommandSpec( domain=domain, @@ -497,7 +511,7 @@ def specs() -> list[CommandSpec]: summary=( "List this organization's HTML documents and its one-level folders. --q searches " "titles. --folder is omitted (every document), root (no folder), or a folder id. " - "Anyone who can read the organization's assets can list; the server decides." + + _READ ), risk_level="read", execution="direct", @@ -511,6 +525,8 @@ def specs() -> list[CommandSpec]: examples=["museoncli html-documents +list --q architecture --folder root"], add_arguments=_add_list_arguments, build_arguments=_build_list_arguments, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), CommandSpec( domain=domain, @@ -538,6 +554,8 @@ def specs() -> list[CommandSpec]: add_arguments=_add_share_arguments, build_arguments=_build_share_arguments, supports_dry_run=True, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), CommandSpec( domain=domain, @@ -557,6 +575,8 @@ def specs() -> list[CommandSpec]: add_arguments=_add_document_arguments, build_arguments=_build_document_arguments, supports_dry_run=True, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), CommandSpec( domain=domain, @@ -576,6 +596,8 @@ def specs() -> list[CommandSpec]: add_arguments=_add_folder_arguments, build_arguments=_build_folder_arguments, supports_dry_run=True, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), CommandSpec( domain=domain, @@ -595,6 +617,8 @@ def specs() -> list[CommandSpec]: add_arguments=_add_install_arguments, build_arguments=_build_install_arguments, supports_dry_run=True, + required_roles=_STAFF_ROLES, + resource_policy=_STAFF_POLICY, ), ] diff --git a/tests/test_html_documents.py b/tests/test_html_documents.py index 0829d9e..fdad07b 100644 --- a/tests/test_html_documents.py +++ b/tests/test_html_documents.py @@ -758,3 +758,54 @@ def answer(request: httpx.Request) -> httpx.Response: assert payload["error"]["server_code"] == "folder_name_taken" assert payload["error"]["message"] == "A folder with this name already exists" assert payload["detail"] == '{"code": "folder_name_taken"}' + + +_PRIVATE = { + "html-documents.upload", + "html-documents.list", + "html-documents.share", + "html-documents.unshare", + "html-documents.folder-create", + "html-documents.install-defaults", +} + + +def test_private_management_catalog_requires_staff_and_stays_organization_bound() -> None: + """Staff is catalog metadata. Organization asset checks stay, and the server enforces both.""" + from museoncli.domains import command_specs + from museoncli.domains._shared import _spec_schema_payload + + html = [spec for spec in command_specs() if spec.domain.value == "html-documents"] + assert {spec.schema_name for spec in html} == _PRIVATE + for spec in html: + assert spec.required_roles == ("staff",) + assert spec.organization_bound is True + assert spec.resource_policy == "staff_with_organization_asset_access" + assert spec.required_scopes == ("agent_cli.access",) + authorization = _spec_schema_payload(spec)["authorization"] + assert authorization == { + "authentication_required": True, + "required_scopes": ["agent_cli.access"], + "required_roles": ["staff"], + "organization_bound": True, + "resource_policy": "staff_with_organization_asset_access", + "enforcement": "museon_server", + } + assert "Museon staff only" in spec.summary + assert "organization" in spec.summary + + skills = next(spec for spec in command_specs() if spec.schema_name == "skills.list") + assert skills.required_roles == ("organization_member",) + assert skills.resource_policy == "server_evaluated_organization_and_resource_access" + + +def test_listing_does_not_stop_a_caller_the_cli_cannot_tell_is_staff(monkeypatch) -> None: + """A non-staff denial is the server's 403. The CLI still sends the organization request.""" + server = Server({("GET", LIBRARY): _library({"folders": [], "root_count": 0, "documents": []})}) + + run(monkeypatch, server, ["html-documents", "+list"]) + + sent = server.requests[0] + assert (sent.method, sent.url.path) == ("GET", LIBRARY) + assert sent.headers["X-Organization-Id"] == ORG + assert "is_staff" not in {name.lower() for name in sent.headers} diff --git a/tests/test_surface_conventions.py b/tests/test_surface_conventions.py index 001f642..d9eb914 100644 --- a/tests/test_surface_conventions.py +++ b/tests/test_surface_conventions.py @@ -190,13 +190,17 @@ def test_command_specs_publish_auth_and_capability_metadata() -> None: if ( spec.schema_name in STAFF_COMMANDS or spec.resource_policy == "staff_global_cloud_phone_management" + or spec.resource_policy == "staff_with_organization_asset_access" ): assert spec.required_roles == ("staff",) elif spec.schema_name in ADMIN_OR_STAFF_COMMANDS: assert spec.required_roles == ("organization_admin_or_staff",) else: assert spec.required_roles == ("organization_member",) - if spec.resource_policy == "staff_global_cloud_phone_management": + if spec.resource_policy == "staff_with_organization_asset_access": + assert spec.domain.value == "html-documents" + assert spec.organization_bound is True + elif spec.resource_policy == "staff_global_cloud_phone_management": assert spec.organization_bound == ( spec.resource == "recovery" or spec.schema_name == "cloud-phone.recovery-job-create"