Joshternet
Menu

Publish with Astro

Astro can publish the declaration as an ordinary static file.

Add the declaration

Create this directory and file in the Astro project’s public directory:

public/
  .well-known/
    josh

A participant affirming Josh identity:

{
  "version": 1,
  "josh": true
}

josh may instead be false for Declined Josh Identity, or omitted for Undeclared Josh Identity. The implementation guide defines those three declarations. Do not invent other values. Publishing any valid version 1 declaration establishes participation according to RFC-JOSH-0002.

Astro copies files from public into the build output. After a normal build:

astro build

the generated site should contain:

dist/
  .well-known/
    josh

The deployed resource is then:

https://example.invalid/.well-known/josh

Check the Astro build

Before deploying, confirm that Astro produced the exact extensionless file:

test -f dist/.well-known/josh
cat dist/.well-known/josh

You can also check the local Astro preview server after a build:

astro preview

Then:

curl -i http://localhost:4321/.well-known/josh

The local check confirms that the resource exists at the expected path. Always repeat the check against the deployed site because production response headers are controlled by the hosting platform. Astro’s preview server does not set Content-Type: application/json for the extensionless file.

Serve it as JSON

RFC-JOSH-0002 associates the declaration with the application/json media type. A server SHOULD return:

Content-Type: application/json

Astro does not choose that media type for an extensionless file. The host does.

Sites published below the origin root

A well-known URI belongs at the root of an origin.

For a site whose public URL is:

https://example.invalid/blog/

the Joshternet declaration is still:

https://example.invalid/.well-known/josh

It is not:

https://example.invalid/blog/.well-known/josh

Astro’s base option does not move the well-known URI. A site that only controls a path under someone else’s origin cannot declare for that origin through this protocol.

Check the deployed URL

Check the live origin with Check a declaration.

Or check the live URL directly:

curl -i https://example.invalid/.well-known/josh

Confirm all of the following:

Publishing the file declares participation. It does not separately notify JoshBot or require registration with joshternet.org.

Stop publishing

To stop declaring participation from an Astro site, remove public/.well-known/josh, rebuild, and redeploy so the live origin no longer serves a valid declaration. Remove any host header rules that exist only for that path.

A deliberate 404 Not Found or 410 Gone at /.well-known/josh indicates that no declaration is currently published. Temporary timeouts, TLS problems, DNS failures, and server errors do not mean the participant intentionally left.

Tested