From download to your first company shortcut.

INSTALLATION & OPERATIONS

Company Links 0.3.0

Company-owned shortcuts, hosted in a private Zogy workspace or run on your infrastructure. Public zo.gy aliases, short-code passes and subdomains are separate products.

Hosted by Zogy

Open https://zogy.grasany.com/company. A workspace owner/admin creates the directory, names the company and chooses prefixes. Hosted access requires Grasany sign-in and current workspace membership; the directory is not public. The included workspace supports 20 members and 1,000 aliases. Higher commercial capacity requires its own verified checkout and entitlement.

Each company is a separate namespace. Two companies may both use go/handbook with different destinations. Hosted URLs and personal device tokens bind to the company identifier. No company server is needed for the hosted HTTPS directory or extension. Native bare hostnames need a company gateway or browser policy: DNS alone cannot select a private tenant or store URL paths.

Self-hosted installation

1. Install Node.js 24+. Extract the source package into a dedicated application folder.
2. Choose a private durable data folder outside application files. Run: node scripts/setup.mjs --data PRIVATE_FOLDER --tenant COMPANY_ID --origin https://links.company.example --hosts go,zo,to
3. Setup writes company.env and operator-access.txt once, with independent administrator, sync and audit credentials. It refuses to overwrite existing setup and does not print credentials. Restrict filesystem access; Windows files inherit folder access controls.
4. Start Node using --env-file pointing to company.env and server.mjs as the entry point. Preserve that environment file and data folder through updates. It supplies CORPORATE_ADMIN_TOKEN, CORPORATE_AUDIT_KEY, CORPORATE_SYNC_TOKEN, CORPORATE_TENANT, CORPORATE_DATA_DIR, CORPORATE_ORIGIN and CORPORATE_HOSTS.
5. The process binds to loopback. Put an IT-controlled HTTPS reverse proxy in front of it; preserve Host. Expose /admin and /api only on the administration hostname with company network/auth/rate-limit controls. Never send operator tokens over HTTP.
6. Configure intranet DNS and proxy hosts for go, zo, to, team, x or chosen internal names. A short-name HTTP entry may redirect to company-controlled HTTPS. Use company TLS policy for internal names. DNS CNAME does not rewrite HTTP Host.
7. Open HTTPS /admin, connect with the private operator token or company OIDC, then create an alias. Start with explicit http://go/handbook or https://links.company.example/handbook. Browsers may treat bare go/handbook as search. /handbook is relative to the current website. Service names admin, api, health and corporate are reserved.

One writer process is supported. writer.lock prevents concurrent writers. After a crash, conclusively stop the owner before removing a stale lock; no automatic takeover is performed. Use a local durable volume, not multi-writer shared network storage.

Move the same names

Hosted Hosting & portability and self-hosted Admin > Updates & backups provide the same portable export and previewed merge import. The file contains private URLs, aliases, prefixes and enabled states, but no account token, operator secret, audit key or billing credential. Keep it private.

The preview names source and destination company and checks the current revision. Confirmation merges incoming aliases, overwrites matching names and retains unrelated aliases. Paused states are preserved; the target records an audit event. Portable exports move content, not the full recovery/audit backup.

Verify health, sign-in, roles, a known alias, a paused alias and extension sync before switching DNS/gateway/browser configuration. Exporting does not erase or automatically disable the original service. Pause the old hosted directory deliberately after the new service is verified.

Browser extension

Chromium extension source is in extension/. IT loads/distributes it under company browser policy. No extension-store listing or publisher signature is claimed.

For hosted use, create a personal read-only device token and copy the exact origin, company UUID, prefixes and directoryPath from Company workspace > Browser devices. Self-hosted connections use a separate CORPORATE_SYNC_TOKEN and leave directoryPath blank. Never put tokens in DNS.

Type go, press Tab, then an alias or configured prefix/alias. Sync runs every five minutes; the session cache expires after at most fifteen. Switching company erases the previous company's token/cache. Restart clears both. Revoked or expired access cannot refresh, but cached aliases can remain until expiry. This does not change DNS or bypass VPN/destination permissions.

Identity, roles and data

Self-hosted OIDC uses CORPORATE_OIDC_ISSUER, CORPORATE_OIDC_CLIENT_ID, CORPORATE_OIDC_CLIENT_SECRET and explicit CORPORATE_OIDC_MEMBERS. Read docs/COMPANY-SSO.md for provider, role, session and revocation requirements. Keep the private operator token for controlled recovery. Hosted access uses current Grasany workspace membership, not automatic company IdP group provisioning.

Owners/admins manage hosted settings, imports, exports and audit access. Editors manage aliases; viewers can read and connect their own scoped device. SCIM and immediate external-IdP session revocation remain separate capabilities.

Usage counters are off by default. Opt-in counters retain up to 90 days, exclude HEAD requests, record no raw IP/email/destination URL, group missing names into one bucket and suppress counts below five. They count requests, not unique people or employee productivity. Buffered self-hosted metrics may lose the last flush interval on crash. Turning hosted counters off deletes retained aggregate history.

Mutations have an integrity chain using a server-held key; self-hosted files are authenticated with the installation audit key. Up to 10,000 events are retained with a checkpoint. Hosted views export the latest 1,000. This detects tampering without the key, not an administrator controlling it or an externally immutable SIEM service. Self-hosted backups accept up to 16 MB and require the original audit key, kept separately; secrets are excluded from JSON backups.

Updates and recovery

Admin > Updates & backups checks the fixed public catalog at zogy.grasany.com without sending company identity, tokens or destinations. It shows version, SHA-256 and a download link. This is a manual source release; checksums detect corruption but are not an independent publisher signature. No code is installed automatically.

Back up the complete private data folder, stop the service, extract the new application into a separate version folder, retain the environment file/data directory, restart and check health/sign-in/roles/known and paused aliases/backup preview. Existing schema-1 data is supported. Keep the prior application and matching protected data backup for rollback. Never execute commands from unverified metadata.

Support checklist

• Search instead of shortcut: use an explicit URL or go + Tab, then check DNS suffix and browser policy.
• 404: check lowercase alias, enabled state and configured host. Unknown private aliases never route to another company or public marketing.
• 401/403: check current membership, operator credential or device expiry. Omit tokens from support tickets.
• 421: Host is not configured. DNS CNAME does not change HTTP Host.
• 409: refresh and review the changed revision before saving/importing again.
• Off-network failure: check VPN and destination access; caching grants neither.
• Lock/integrity error: preserve data, verify the owner process stopped, then restore a known backup with its key.

Support: https://grasany.com/contact/. Share version, OS, sanitized error and failed step; omit secrets, private exports and URLs. Paid corporate checkout/licensing, production publisher signing, automatic installation, extension-store distribution, SCIM and an enterprise SLA require separate completed acceptance and are not claimed by this package.

COMPANY SIGN-IN & ROLES

Company sign-in and roles

Configure these server-side variables using your company's secret manager:

• CORPORATE_OIDC_ISSUER: exact HTTPS issuer from your IT-managed identity provider.
• CORPORATE_OIDC_CLIENT_ID and CORPORATE_OIDC_CLIENT_SECRET: confidential web client.
• Register exactly https://YOUR_ADMIN_HOST/auth/company/callback as its redirect URI.
• CORPORATE_OIDC_MEMBERS: JSON array, e.g. [{"subject":"IDP_SUBJECT","role":"admin"}].

Subjects are opaque provider subject identifiers, not email addresses. Roles are assigned by IT in local service configuration: admin, editor, auditor, viewer. Restart after changing configuration; restart invalidates all sessions. Admins can manage aliases/backups/updates; editors can change aliases; auditors can inspect usage and audit; viewers can read the directory. Identity claims never assign roles. No automatic domain enrolment or email-based administrator bootstrap occurs.

Supported providers must advertise RS256, S256 PKCE and client_secret_basic, with HTTPS discovery, authorization, token and JWKS endpoints on the exact issuer origin. Providers using a different discovery layout or endpoint origin need an explicitly reviewed adapter; do not disable these checks. The service uses code flow with browser-bound single-use state, nonce, PKCE and server-held client credentials. Cookies require HTTPS and use HttpOnly, Secure, SameSite=Lax and __Host- names. Sessions expire after eight hours or thirty minutes idle. Local sign-out revokes the service session; it does not sign out other company applications. No access or refresh token is persisted. Removing a configured member takes effect on restart. An identity-provider deactivation alone does not immediately revoke an existing local session; SCIM/back-channel logout is not implemented in this version.

Keep CORPORATE_ADMIN_TOKEN strong and private as a break-glass operator credential. It remains a full administrator; do not distribute it to employees or extensions. Use the separate sync token for the company-wide extension directory. These tokens should be rotated through the service configuration and company secret manager. Directory changes record the hashed issuer/subject as their audit actor.

Verification uses a synthetic RSA identity provider and actual local HTTP callback, role and cookie boundaries. A customer must register its own client and verify its actual provider before production use; no customer identity service was contacted.

BROWSER EXTENSION EVALUATION

Company Links browser extension (development source)

Chrome and Edge Manifest V3. Load this directory as an unpacked extension in an approved development browser profile. This is not a store-signed or managed enterprise distribution. No remote scripts or content scripts run.

Hosted company directory

Open the hosted company workspace, choose Browser devices and create a personal read-only connection. Its JSON contains the HTTPS origin, company identifier, exact directoryPath, configured prefixes and a once-only token. Enter those in the extension options. Treat the token as private: it reads enabled destinations. Hosted tokens expire within 30 days and can be revoked individually. Every sync checks current company membership, company enabled state and token expiry. The only permitted custom path is /api/company/<company-id>/sync.

Self-hosted directory

IT generates a separate CORPORATE_SYNC_TOKEN, at least 32 characters and distinct from the administrator token, then supplies the HTTPS origin, tenant, configured prefixes and read-only token through its own secure channel. Leave directoryPath blank for /api/extension-directory. The self-hosted token is shared and reads all enabled aliases: this build does not claim per-person self-hosted device enrolment. Never enter an administrator token in the extension.

Lookup and lifetime

Only the configured HTTPS origin receives an optional host permission. Type go, press Tab, then enter handbook, /handbook or a configured prefix such as zo/handbook. Lookup reads the in-memory session cache, without waiting for the network. Sync runs every five minutes; snapshots expire after at most 15 minutes, or sooner if the hosted token expires. Browser restart/disconnect and company switches clear the cache. A 401/403 clears it at the next sync. Network failures retain only an unexpired snapshot. Status pages never reveal the token.

This does not intercept arbitrary bare host text, change DNS or rewrite another site's relative paths. Company DNS plus a gateway handles native go/alias; the extension command handles off-network lookup. Destinations still enforce their VPN and access permissions. Revocation cannot erase a previously viewed URL or already-issued cache before its expiry. No cloud browser-sync storage is used. Managed distribution and persistent encrypted enrolment remain separate work.