Gusnais Skill

Gusnais (Ruby-China/Homeland compatible) API integration with web-parity behavior and permission-consistent UX. Use when users want to connect using only CLI...

Security Scan

The skill's code and instructions appear to implement a legitimate Gusnais OAuth/API client, but the package metadata omits required environment variables and there are small coherence issues (token persistence to disk, undeclared secrets) you should review before installing.

Purpose & Capability

Name, description, SKILL.md, and included scripts consistently implement a Gusnais/Homeland-compatible API client using OAuth (CLIENT_ID/CLIENT_SECRET). That capability is coherent with the stated purpose. However the registry metadata declares no required environment variables even though the SKILL.md and scripts clearly require CLIENT_ID and CLIENT_SECRET (and optionally TOKEN_STORE_PATH). This mismatch is an integrity/packaging concern.

Instruction Scope

SKILL.md confines runtime actions to OAuth flow, token validation (/api/v3/users/me), reading the two reference docs, and using the two included scripts. The scripts only perform HTTP calls to the gusnais.com site and read/write a local token store JSON. They do not attempt broader system access or unexpected network endpoints. The instructions recommend persisting tokens to disk which expands scope (local file I/O) and should be considered.

Install Mechanism

No install script or external downloads are declared (instruction-only install). The code files are bundled with the skill; there is no remote fetch or archive extraction. This is lower-risk than arbitrary remote installs.

Credentials

The skill requires CLIENT_ID and CLIENT_SECRET (and may use OAUTH_CODE, REDIRECT_URI, TOKEN_STORE_PATH) to function, which is proportionate to an OAuth client. But the registry metadata lists no required env vars (incoherent). The scripts persist client_secret and refresh tokens into a JSON file (TOKEN_STORE_PATH) on disk, which increases sensitive data exposure and must be intentionally approved by the user.

Persistence & Privilege

The skill does not request always:true and does not modify other skills. It writes/updates a token-store JSON file and sets file permissions to 0600 — normal for a client but it does create persistent credentials on disk which raises confidentiality considerations for the user.

What to consider before installing

This skill mostly does what it claims: an OAuth client and plugin API caller for gusnais.com. However: (1) the registry metadata incorrectly lists no required env vars while the code and SKILL.md require CLIENT_ID and CLIENT_SECRET — treat that as a packaging/integrity red flag and confirm the source before giving secrets; (2) the bootstrap and client scripts will persist client_secret, access_token, and refresh_token into a JSON file if you set TOKEN_STORE_PATH — store that file only in a safe location and prefer 0600 perms; (3) review the two included Python scripts yourself (they are bundled and will be run) or run them in a sandbox/isolated environment if you must test; (4) if you don't trust the publisher, prefer to perform the OAuth exchange manually and create a token-store yourself rather than handing CLIENT_SECRET to an unvetted skill. If the owner/publisher is unknown, ask for provenance, a canonical homepage, or a signed release before installing.

Implement Gusnais API integration that mirrors web behavior and permission boundaries.

Require only two user inputs

• CLIENT_ID
• CLIENT_SECRET

Do not ask for base URL, OAuth paths, account IDs, scope defaults, pagination defaults, or serializer mappings unless discovery fails.

Auto-complete platform config

Use these defaults:

• Site: https://gusnais.com
• OAuth Authorize: /oauth/authorize
• OAuth Token: /oauth/token
• OAuth Revoke: /oauth/revoke
• API Base: /api/v3

Auth flow

1. Build authorization URL automatically.
2. Exchange authorization code for access_token and refresh_token.
3. Validate token with GET /api/v3/users/me.
4. Refresh once on 401; if refresh fails, request re-auth.

Prefer Authorization header for requests:

• Authorization: Bearer <access_token>

Keep access_token query fallback for compatibility with Homeland API behavior.

Web parity contract

Match gusnais.com UX and permission behavior:

1. Read abilities first when available
   • Resource-level actions must follow returned abilities.
2. Dual check
   • UI check (visible/enabled) using abilities.
   • Execution check with real API call and status code handling.
3. No privilege escalation
   • Never assume admin/mod privileges in client logic.
4. Respect hidden/inaccessible resources
   • 404/403 semantics should stay consistent with server behavior.

Capability gating model

For each action produce:

• visible: true|false
• enabled: true|false
• reason: ok|no_permission|auth_required|resource_unavailable|validation_error
• source: abilities|server_status|policy

Endpoint behavior alignment

Use endpoint mapping in references/endpoints.md and serializer notes for normalized outputs.

Keep defaults aligned with docs:

• offset default: 0
• limit default: 20
• limit range on list endpoints: 1..150 (or endpoint-specific documented max)
• topic list default type=last_actived

For plugin domain operations (press/note/site/jobs):

• Read plugin web-route parity and API contract in references/endpoints.md.
• Read permission nuances in references/permission-parity.md.
• Treat 404 on plugin API endpoints as resource_unavailable unless deployment has enabled those API routes.

Topic action safety

For POST /api/v3/topics/:id/action?type=:type (ban|excellent|unexcellent|close|open):

• Gate by abilities if present.
• Enforce final server response.
• Never expose action as enabled when denied.

Error mapping

Normalize API errors without changing meaning:

• 400 -> validation_error
• 401 -> auth_required (refresh then retry once)
• 403 -> no_permission
• 404 -> resource_unavailable
• 500 -> server_error

Return original server error text when available.

Rate limiting / retries

• Respect Retry-After on 429.
• Use exponential backoff with jitter for transient 5xx.
• Avoid one-item tight loops for batch writes.

Read these references before implementation

• references/endpoints.md
• references/permission-parity.md

Bootstrap script

Use scripts/gusnais_bootstrap.py to initialize runtime config from CLIENT_ID and CLIENT_SECRET.

Recommended:

• set TOKEN_STORE_PATH when exchanging code, so refreshable tokens are persisted to JSON for long-lived automation.

Plugin API client script

Use scripts/gusnais_plugin_client.py for plugin API read/write calls with:

• auto refresh before expiry and on 401;
• one retry after refresh;
• normalized status reason mapping;
• capability hint extraction from abilities;
• action-level payload guardrails to avoid avoidable 400/500 (e.g. press create summary fallback).

Current deployment notes (2026-03-19):

• Press API is mounted for read/write (/api/v3/press/posts*).
• Note API is mounted for read/write (/api/v3/note/notes*).
• Site API is mounted for sites CRUD + site_nodes list; undestroy/site_node writes are not mounted.
• Treat any unmounted plugin API route as resource_unavailable and avoid repeated retries.