starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-10-21 16:03:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(skills): publish sharing lifecycle guides

Browse Source
This commit is contained in:
Jinwoo-H
2026-08-12 09:15:09 -04:00
parent 029e474884
commit dbf2e682ea
5 changed files with 202 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/agent-skill-sharing-implementation-checklist.md
+12 -7
View File
@@ -1331,9 +1331,11 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr
three explicit controls.
- [ ] Disable the affected operation on unexplained digest mismatch, archive containment failure, data leak,
unrecoverable local mutation, or cross-tenant authorization defect.
- [ ] Publish user documentation for sharing, access, install destinations, updates, rollback,
removal, retention, and trust.
- [ ] Publish admin documentation for organization access, user departure, deletion, and retention.
- [x] Publish user documentation for sharing, access, install destinations, updates, rollback,
removal, retention, and trust in
[`docs/reference/sharing-agent-skills.md`](./reference/sharing-agent-skills.md).
- [x] Publish admin documentation for organization access, user departure, deletion, and retention
in [`docs/reference/admin-agent-skill-sharing.md`](./reference/admin-agent-skill-sharing.md).
- [ ] Remove rollout flags only after sustained healthy usage and a reviewed decision.
### First-release gate
@@ -1344,8 +1346,10 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr
- [ ] Real SSH paths and host-owned resolution pass.
- [ ] Mixed-version tests pass in both directions.
- [ ] Cancellation and crash recovery pass during transfer and every commit boundary.
- [ ] Durable-share authorization, revocation lag, retention, deletion, and recovery are documented
and tested.
- [x] Durable-share authorization, revocation lag, retention, deletion, and recovery are documented
and tested. The user/admin guides document the lifecycle; Cloud route, integration, restore,
and cleanup suites cover the implemented contract. Automatic one-day quarantine deletion
remains a separate time-gated infrastructure observation.
- [ ] The UI identifies author, organization, scripts, and executable content before install.
- [ ] Telemetry, logs, and diagnostic bundles contain no credentials or private contents.
- [ ] Kill switches are tested without affecting discovery or existing installations.
@@ -1360,5 +1364,6 @@ metrics, lifecycle/migration visibility, budget coverage, and reviewed alert thr
- [ ] Evaluate an explicit, reviewable project desired-state manifest.
- [ ] Evaluate direct machine-to-machine transfer if Cloud persistence is not appropriate.
- [ ] Define offline convergence without durable shared credentials.
- [ ] Document organization removal, user departure, package retention, and reconciliation
semantics before enabling policy-driven installs.
- [x] Document organization removal, user departure, package retention, and reconciliation
semantics before enabling policy-driven installs. The admin guide explicitly leaves legal
retention and ownership-transfer approval as human release gates.
docs/agent-skill-sharing-installation-plan.md
+2 -1
View File
@@ -1154,7 +1154,8 @@ The detailed threat register and residual release gates live in
- Treat `SKILL.md` and packaged scripts as executable code for trust messaging.
- Show author, organization, version, digest, file summary, and executable files before install.
- Require authentication for private share resolution and every download grant.
- Require the exact active bearer share ID for recipient resolution and every download grant;
require authentication for publication and owner management.
- Bind grants to one package version, digest, maximum byte count, and short expiration.
- Validate grant and redirect hosts to prevent server-side request forgery.
- Never execute package scripts during installation.
docs/reference/admin-agent-skill-sharing.md
+97
View File
@@ -0,0 +1,97 @@
# Administer agent skill sharing
This guide describes the first-release access, lifecycle, retention, and recovery contract for
Orca skill sharing. The operator runbook remains the source of truth for incident commands and
environment-specific procedures.
## Access model
- Shared bundles are unlisted bearer resources. Orca provides no public browse, search, recipient
inventory, or package index.
- Anyone with an active, unexpired link can inspect the package and request a short-lived download
grant without signing in.
- Publishing, package/version management, owned-link inventory, revocation, and deletion require
an authenticated package owner with current organization access.
- Missing, expired, revoked, deleted, and unauthorized resources return the same non-disclosing
response.
- Desktop and remote runtimes receive no GCP identity or long-lived storage credential.
The durable share ID is a credential. Do not put it in tickets, logs, analytics, or support
bundles. Use revocation if a link may have reached an unintended recipient.
## Revocation and deletion
Revoking a share immediately blocks new resolution and download grants. A generation-bound grant
issued before revocation can work until its five-minute expiry. Already installed skills remain on
recipient machines.
Package deletion follows this order:
1. Mark the package deleted and revoke its active shares.
2. Dereference retained versions transactionally.
3. Delete only an object generation that no retained version references.
4. Reconcile bounded pending deletions after partial database or GCS failures.
A version cannot be deleted while an active pinned share references it. Deletion uses the exact
recorded GCS generation and never overwrites an immutable published key.
## User and organization departure
Packages belong to an owner tenant and record the publishing user. In an organization tenant,
another current member can manage the package after its publisher leaves; Orca does not rewrite
the recorded creator. Removing a user does not automatically revoke the organization's links,
delete packages, or remove installed copies.
Before deleting an organization tenant:
1. Disable new grants for the tenant.
2. Have an authorized operator inventory and revoke active shares.
3. Decide whether packages transfer to another authorized owner, remain retained, or are deleted.
4. Resolve legal hold, erasure, and audit-retention requirements.
5. Apply the coordinated metadata and object lifecycle; do not bypass reference checks.
The product does not yet encode a universal ownership-transfer or legal-retention policy. Privacy,
security, and the organization owner must approve the applicable policy before external rollout.
Until that decision is recorded, preserve metadata and soft-deleted generations rather than
guessing.
## Retention contract
| Data | Default behavior |
| -------------------------------------- | --------------------------------------------------------- |
| Upload policy and pending upload row | Expires after 15 minutes |
| Abandoned `uploads/` quarantine object | Deleted by GCS after one day |
| Published immutable package object | No age-based deletion; retained while referenced |
| Issued download grant | Expires after five minutes |
| Deleted package object | Recoverable through GCS soft delete for seven days |
| PostgreSQL metadata | Covered by backups and seven-day point-in-time recovery |
| Installed recipient copy | Independent local data; Cloud deletion does not remove it |
| Audit event | Follows the approved audit-retention policy |
Organization retention, legal hold, and erasure requirements take precedence over product rollback
retention. Product deletion is not a legal-hold mechanism.
## Audit and privacy
Audit records may include package/version IDs, actor IDs, event category, outcome, and timestamp.
They must not include skill contents, filenames, manifests, organization membership lists, local
paths, durable share URLs, upload policies, download grants, or credentials. Anonymous abuse
controls must not persist raw requester IP addresses.
Normal Cloud logs are limited to route, method, status, duration, and bounded failure categories.
Use seeded privacy canaries when validating staging logs and diagnostic exports.
## Recovery and incident controls
Upload, download, and remote-install operations have independent kill switches. Disable the
narrowest affected operation; existing local discovery and installs continue to work.
Coordinate PostgreSQL point-in-time recovery with GCS generation recovery. Restore metadata into
an isolated database, identify exact referenced generations, restore only matching soft-deleted
objects, verify archive and package identities, then transactionally repoint metadata. Keep grants
disabled until bearer preview and a generation-bound download pass.
See the Orca Cloud `docs/skill-sharing-runbook.md` for deployment controls, reconciliation,
saturation, signing failures, database outages, and the guarded restore workflow. Security
invariants and unresolved release gates are recorded in
[Agent skill sharing threat model](./agent-skill-sharing-threat-model.md).
docs/reference/agent-skill-sharing-threat-model.md
+3 -2
View File
@@ -10,7 +10,8 @@ resolution, local and remote installation, provider placement, update, rollback,
operator recovery. It applies to macOS, Linux, native Windows, WSL, paired Orca runtimes, and SSH
targets.
Private means access-controlled to authenticated Orca users and organizations. V1 is not
Private means unlisted: an unpredictable active share ID is a bearer credential, while publication
and management remain access-controlled to authenticated Orca users and organizations. V1 is not
end-to-end encrypted from Orca Cloud operators. A skill is code from its author: `SKILL.md` can
change agent behavior and packaged scripts may be executed later by a user or agent, although the
installer itself never executes package content.
@@ -71,7 +72,7 @@ Trust boundaries are:
| TM-06 | A crash between renames or receipt publication loses both old and new versions. | Same-filesystem staging, durable journals, backups, flushed receipt replacement, bounded recovery, and ownership tokens protect every commit boundary. Failure injection covers every journal transition. | Real process termination and disk/antivirus contention tests remain required. |
| TM-07 | A grant leaks through redirects, userinfo, an insecure scheme, DNS/host confusion, or an oversized stream. | Cloud requests reject redirects. Package downloads require configured origins and HTTPS, reject URL credentials and cross-origin redirects, cap redirect count, recheck expiry, stream exact expected bytes, and verify archive/package digests. | Validate approved production origins and exercise malicious network cases in staging. |
| TM-08 | Reuse of an upload ID, wrong tenant, wrong key, stale generation, or quarantine object publishes attacker-selected bytes. | Random tenant-bound upload rows, signed POST conditions, expiry, exact metadata/key/type/size validation, generation-fenced reads, streamed validation, and idempotent finalization fail closed. | Staging GCS integration must cover stale generations and lifecycle deletion. |
| TM-09 | IDOR or stale organization membership exposes package metadata or creates a fresh grant. | Every resolution and grant request authenticates and re-evaluates current package/share ACLs. Membership removal is tested between preview, grant, and download. Not-found responses hide unauthorized existence. | Human authorization review and organization-departure policy approval remain required. |
| TM-09 | IDOR, stale organization membership, or a guessed identifier exposes package management data or bearer-protected content. | Management requests authenticate and re-evaluate current ownership. Recipient preview and grants require the exact unpredictable, active bearer share ID and ignore legacy ACL rows. Not-found responses hide unauthorized existence. | Human authorization review and organization-departure policy approval remain required. |
| TM-10 | Content-addressed deduplication discloses another tenant's package through response shape or timing. | Tenant-scoped APIs never expose GCS keys, generations, or whether an object already existed; existing-object reuse verifies both archive and logical package identity. | A staging timing test and reviewed mitigation threshold are still required before external rollout. |
| TM-11 | A compromised renderer, old client, or arbitrary RPC caller sends credentials, local paths, unknown opcodes, or unsupported operations to a host. | Main owns auth tokens and grants; remote requests use strict schemas and capabilities; package transfer is separate from install; no stream opcode was added; mixed versions fail with update-required results. | Real client-newer/server-newer and SSH parity gates remain required. |
| TM-12 | Transfer replay, overlap, disconnect, or abandoned staging consumes disk or commits different bytes. | Session count, idle time, total bytes, and chunk size are bounded. Offsets are monotonic, identical retry is idempotent, changed replay fails, commit hashes the exact staged file, and cancellation/disconnect cleanup is bounded. | Exercise offline-GCS and real disconnects at every transfer boundary. |
docs/reference/sharing-agent-skills.md
+88
View File
@@ -0,0 +1,88 @@
# Share and install agent skills
Orca can put one skill or a bundle of skills behind one unlisted, revocable link. Shared bundles
do not appear in search, a catalog, or a public index. Anyone who has an active link can inspect
and install its contents without signing in, so treat the link like a credential.
## Share skills
Publishing and link management require an Orca account in the desktop app.
1. Open **Skills** and choose **Share skills**.
2. Select one or more skills. One link can contain a large collection, such as 30 skills.
3. Review the bundle name, included skills and files, scripts, executable files, digest, account,
and optional release notes.
4. Choose **Publish skill**, **Publish bundle**, or **Publish new version**, then copy the link.
Orca publishes an immutable version. Later changes do not silently alter a link's current bytes;
publish a new version to update the Cloud package.
Use **Settings → Share Skills** to copy or revoke active links. Revocation blocks new previews and
download grants. A grant issued immediately before revocation can remain usable for up to five
minutes, and revocation does not remove copies that recipients already installed.
## Install from a link
Opening an Orca skill link shows a preview before changing any files. You can also open **Skills**,
choose **Install from link**, and paste the URL.
1. Verify the author and organization.
2. Review the version, release notes, included skills, scripts, executable files, and digest.
3. Select all skills or only the ones you want.
4. Choose the destination machine and either global or workspace scope.
5. Review new, unchanged, updated, and conflicting skills, then choose **Install N skills**.
Supported destinations include the local machine, paired Orca runtimes, WSL, and SSH hosts. The
destination runtime resolves its own home and workspace paths, so folder workspaces and remote
filesystems do not borrow paths from the client machine.
Orca keeps one canonical installed copy and places it where supported agents can discover it.
Current provider coverage is documented in
[Agent skill provider paths](./agent-skill-provider-paths.md).
## Conflicts, updates, and rollback
**Keep local** is the default when an existing skill differs. Orca replaces modified content only
after you explicitly choose to discard it.
Open **Skills → Manage installs** to inspect managed skills and their immutable version history.
Installing the latest version performs an update; selecting an older retained version performs a
rollback. Both use the same protected install transaction. If a bundle changes between versions,
Orca updates only the selected skills that still exist in that version.
An interrupted install is recovered on restart. If Orca reports a conflict or partial result,
review the named skill and retry; completed skills do not need to be installed again.
## Remove an installed skill
Use **Skills → Manage installs → Remove**. Orca removes only copies and provider placements that it
owns and can verify. Modified or unowned files are preserved and reported. Discarding modified
content requires a separate explicit confirmation.
Removing a local install does not revoke its share or delete its Cloud package. Likewise,
revoking or deleting Cloud data does not reach into recipients' machines.
## Retention and deletion
- Upload grants expire after 15 minutes.
- Abandoned upload bytes are removed from quarantine after one day.
- Published versions have no automatic age-based deletion.
- Deleting a package revokes its links before unreferenced objects are deleted.
- Deleted GCS objects remain operator-recoverable through a seven-day soft-delete window.
- Installed copies remain until someone removes them on each destination machine.
Organization legal or retention requirements can override normal rollback and deletion timing.
## Trust and privacy
A skill is code from its author. `SKILL.md` can change agent behavior, and included scripts or
executables may run later when a person or agent uses the skill. Orca validates the package and
never executes its contents during installation, but you should install only from people you trust
and review unexpected scripts or executable files.
Orca records bounded operational identifiers and outcomes. Normal logs, telemetry, and support
bundles exclude skill contents, filenames, manifests, local paths, share URLs, upload policies,
download grants, credentials, and access lists.
If a link no longer works, ask its owner for an active link. Missing, expired, revoked, and deleted
links intentionally show the same response so Orca does not disclose private package existence.